@orkestrel/process 0.0.9 → 0.0.11

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

@@ -1,23 +1,24 @@
 import { Buffer as Buffer_2 } from 'node:buffer';
-import { DetachOptions } from '@orkestrel/process';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { ExecutableOptions } from '@orkestrel/process';
-import { ExecuteInput } from '@orkestrel/process';
-import { ExecuteOptions } from '@orkestrel/process';
-import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteSyncOptions } from '@orkestrel/process';
-import { ProcessCommand } from '@orkestrel/process';
-import { ProcessEventMap } from '@orkestrel/process';
-import { ProcessExit } from '@orkestrel/process';
-import { ProcessInterface } from '@orkestrel/process';
-import { ProcessManagerEventMap } from '@orkestrel/process';
-import { ProcessManagerInterface } from '@orkestrel/process';
-import { ProcessManagerOptions } from '@orkestrel/process';
-import { ProcessOptions } from '@orkestrel/process';
-import { SessionEventMap } from '@orkestrel/process';
-import { SessionInterface } from '@orkestrel/process';
-import { SessionOptions } from '@orkestrel/process';
-import { SpawnInput } from '@orkestrel/process';
+import type { DetachOptions } from '@orkestrel/process';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { ExecutableOptions } from '@orkestrel/process';
+import type { ExecuteInput } from '@orkestrel/process';
+import type { ExecuteOptions } from '@orkestrel/process';
+import type { ExecuteResult } from '@orkestrel/process';
+import type { ExecuteSyncOptions } from '@orkestrel/process';
+import type { ProcessCommand } from '@orkestrel/process';
+import type { ProcessEventMap } from '@orkestrel/process';
+import type { ProcessExit } from '@orkestrel/process';
+import type { ProcessInterface } from '@orkestrel/process';
+import type { ProcessManagerEventMap } from '@orkestrel/process';
+import type { ProcessManagerInterface } from '@orkestrel/process';
+import type { ProcessManagerOptions } from '@orkestrel/process';
+import type { ProcessOptions } from '@orkestrel/process';
+import type { Readable } from 'node:stream';
+import type { SessionEventMap } from '@orkestrel/process';
+import type { SessionInterface } from '@orkestrel/process';
+import type { SessionOptions } from '@orkestrel/process';
+import type { SpawnInput } from '@orkestrel/process';
 
 /**
  * Builds the executable candidates an explicit platform would search.
@@ -143,26 +144,37 @@ export declare function buildSpawn(command: ProcessCommand, options?: Executable
 export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
 
 /**
- * Creates one supervised child process.
+ * Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+ * holds the published contract rather than the `Process` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link ProcessInterface}
  *
- * @example
+ * @example Supervise a child and read its lines
  * ```ts
  * import { createProcess } from '@orkestrel/process/server'
  *
  * const child = createProcess({
- * 	command: { file: 'node', arguments: ['--version'] },
+ * 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
  * 	workspace: process.cwd(),
- * 	grace: 5000,
+ * 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
  * })
+ *
+ * const lines: string[] = []
+ * for await (const line of child.lines) lines.push(line)
+ * lines // ['ready', 'done']
+ *
+ * const exit = await child.exit
+ * exit.code // 0
+ * await child.destroy()
  * ```
  */
 export declare function createProcess(options: ProcessOptions): ProcessInterface;
 
 /**
- * Creates one keyed registry of supervised child processes.
+ * Creates one empty keyed registry of supervised child processes and returns it as a
+ * {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+ * `ProcessManager` class.
  *
  * @param options - Initial fleet-level observation hooks and listener-error handling
  * @returns The {@link ProcessManagerInterface} registry
@@ -177,7 +189,8 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
 /**
- * Creates one raw byte session over a supervised child process.
+ * Creates one raw byte session over a supervised child process and returns it as a
+ * {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link SessionInterface}
@@ -301,14 +314,14 @@ export declare function formatCommand(command: ProcessCommand): string;
  * initiated against a pid the host may have reused.
  *
  * @param child - The child boundary
- * @returns True when the process has exited; false while it is live
+ * @returns True if the process has exited; false otherwise
  *
  * @example
  * ```ts
  * isExited({ exitCode: 0, signalCode: null }) // true
  * ```
  */
-export declare function isExited(child: Pick<ProcessChild, 'exitCode' | 'signalCode'>): boolean;
+export declare function isExited(child: Pick<ProcessChildInterface, 'exitCode' | 'signalCode'>): boolean;
 
 /**
  * Checks whether a path names a regular file.
@@ -318,7 +331,7 @@ export declare function isExited(child: Pick<ProcessChild, 'exitCode' | 'signalC
  * command. An unreadable or malformed path reports `false` rather than throwing.
  *
  * @param target - The absolute or relative path to inspect
- * @returns True when the path resolves to a regular file; false otherwise
+ * @returns True if the path resolves to a regular file; false otherwise
  *
  * @example
  * ```ts
@@ -347,7 +360,7 @@ export declare function isFile(target: string): boolean;
  * killProcess(child, 'SIGTERM')
  * ```
  */
-export declare function killProcess(child: Pick<ProcessChild, 'pid' | 'kill'>, signal: NodeJS.Signals): void;
+export declare function killProcess(child: Pick<ProcessChildInterface, 'pid' | 'kill'>, signal: NodeJS.Signals): void;
 
 /**
  * Kills one Windows process tree through `taskkill`.
@@ -361,7 +374,7 @@ export declare function killProcess(child: Pick<ProcessChild, 'pid' | 'kill'>, s
  *
  * @param pid - The root process id of the tree to end
  * @param timeout - The milliseconds the utility is given before it is killed
- * @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
+ * @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
  *
  * @example
  * ```ts
@@ -408,7 +421,8 @@ 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;
 
 /**
- * Supervises one child while keeping every observation channel aligned at termination.
+ * Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+ * every observation channel aligned at termination.
  *
  * @remarks
  * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -441,34 +455,34 @@ export declare function mergePlatformEnvironment(platform: NodeJS.Platform, pare
 export declare class Process implements ProcessInterface {
     #private;
     /**
-     * Spawn one child process and begin stream capture.
+     * Spawns one child process and begins stream capture.
      *
      * @param options - Command, workspace, termination, capture, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
     constructor(options: ProcessOptions);
-    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
-    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
     get code(): number | null;
-    /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+    /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
     get signal(): string | null;
-    /** The typed lifecycle observation surface. */
+    /** Holds the typed lifecycle observation surface. */
     get emitter(): EmitterInterface<ProcessEventMap>;
-    /** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
+    /** Yields 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, frozen at the terminal moment. */
+    /** Holds 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. */
+    /** Reports whether the `lines` stream omitted output after a retention bound was reached. */
     get truncated(): boolean;
-    /** True after the terminal moment arrived and `exit` settled. */
+    /** Reports whether the terminal moment arrived and `exit` settled. */
     get settled(): boolean;
-    /** True after termination began, including after the terminal moment. */
+    /** Reports whether termination began, including after the terminal moment. */
     get stopping(): boolean;
-    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    /** Settles with 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.
+     * Writes one line to the open standard-input channel.
      *
      * @remarks
      * Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
@@ -482,7 +496,7 @@ export declare class Process implements ProcessInterface {
      * for bytes the package is about to discard.
      *
      * @param text - The line text without its trailing newline
-     * @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`
+     * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
      */
     send(text: string): Promise<boolean>;
     /**
@@ -494,7 +508,7 @@ export declare class Process implements ProcessInterface {
      * 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
+     * @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
      */
     stop(): Promise<boolean>;
     /**
@@ -509,15 +523,7 @@ export declare class Process implements ProcessInterface {
 }
 
 /**
- * The Node-side contracts of `@orkestrel/process/server`.
- *
- * @remarks
- * The host-independent contracts live in `@orkestrel/process`. This module declares only what a
- * Node child process boundary requires, which the published contracts cannot express without
- * naming `node:child_process` types.
- */
-/**
- * The child boundary the termination helpers drive.
+ * Represents the child boundary the termination helpers drive.
  *
  * @remarks
  * A `ChildProcess` satisfies this structurally, and so does any object carrying the same
@@ -531,30 +537,42 @@ export declare class Process implements ProcessInterface {
  * the route that reaches it: `killProcess` signals the negated `pid` first and falls back to `kill`
  * when the host reports that no group owns that pid.
  */
-export declare interface ProcessChild {
-    /** The process id the host assigned, or `undefined` when the spawn never produced one. */
+export declare interface ProcessChildInterface {
+    /** Holds the process id the host assigned, or `undefined` when the spawn never produced one. */
     readonly pid?: number | undefined;
-    /** The exit code, or `null` while the process is live or a signal ended it. */
+    /** Holds the exit code, or `null` while the process is live or a signal ended it. */
     readonly exitCode: number | null;
-    /** The terminating signal name, or `null` while the process is live or it exited on its own. */
+    /** Holds the terminating signal name, or `null` while the process is live or it exited on its own. */
     readonly signalCode: string | null;
     /**
-     * Deliver one signal to the process.
+     * Delivers one signal to the process.
      *
      * @param signal - The signal to deliver
-     * @returns True when the host accepted the signal; false otherwise
+     * @returns True if the host accepted the signal; false otherwise
+     *
+     * @example
+     * ```ts
+     * const accepted = child.kill('SIGTERM')
+     * accepted // true
+     * ```
      */
     kill(signal: NodeJS.Signals): boolean;
     /**
-     * Register a one-shot listener for the native exit or stream close.
+     * Registers a one-shot listener for the native exit or stream close.
      *
      * @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
+     *
+     * @example
+     * ```ts
+     * const settle = (): void => undefined
+     * child.once('exit', settle)
+     * ```
      */
     once(event: 'exit' | 'close', listener: () => void): unknown;
     /**
-     * Release one previously registered exit or close listener.
+     * Releases one previously registered exit or close listener.
      *
      * @remarks
      * `waitForExit` releases its `exit` listener, and `waitForClose` releases its `close` listener, so
@@ -563,12 +581,20 @@ export declare interface ProcessChild {
      * @param event - The `exit` or `close` event name
      * @param listener - The listener registered through `once`
      * @returns Whatever the emitter returns, which the helpers ignore
+     *
+     * @example
+     * ```ts
+     * const settle = (): void => undefined
+     * child.once('exit', settle)
+     * child.off('exit', settle)
+     * ```
      */
     off(event: 'exit' | 'close', listener: () => void): unknown;
 }
 
 /**
- * A keyed registry of live supervised child processes.
+ * Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+ * every live child on teardown.
  *
  * @remarks
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -599,30 +625,30 @@ export declare interface ProcessChild {
 export declare class ProcessManager implements ProcessManagerInterface {
     #private;
     /**
-     * Construct a process registry.
+     * Constructs a process registry.
      *
      * @param options - Initial fleet-level observation hooks and listener-error handling
      */
     constructor(options?: ProcessManagerOptions);
-    /** The typed fleet-level observation surface. */
+    /** Holds the typed fleet-level observation surface. */
     get emitter(): EmitterInterface<ProcessManagerEventMap>;
-    /** The number of live children. */
+    /** Counts the live children. */
     get count(): number;
     /**
-     * The live child under `id`, or `undefined` when none is.
+     * Returns the live child under `id`, or `undefined` when none is.
      *
      * @param id - The registry key
      * @returns The child, or `undefined`
      */
     process(id: string): ProcessInterface | undefined;
     /**
-     * A snapshot of every live child.
+     * Returns a snapshot of every live child.
      *
      * @returns The live children in launch order
      */
     processes(): readonly ProcessInterface[];
     /**
-     * Spawn and register one child under `id`.
+     * Spawns and registers one child under `id`.
      *
      * @remarks
      * {@link Process} reads every option before it spawns, so a caller's own option getter runs while
@@ -640,27 +666,27 @@ export declare class ProcessManager implements ProcessManagerInterface {
      */
     launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
-     * Terminate the named children and await their exit.
+     * Terminates the named children and awaits their exit.
      *
      * @param ids - The registry keys to stop
-     * @returns True when every named child was live and its exit was confirmed; false otherwise
+     * @returns True if every named child was live and its exit was confirmed; false otherwise
      */
     stop(ids: readonly string[]): Promise<boolean>;
     /**
-     * Terminate one child and await its exit.
+     * Terminates one child and awaits its exit.
      *
      * @param id - The registry key to stop
-     * @returns True when the child was live and its exit was confirmed; false when the id was not live or the confirmation deadline elapsed
+     * @returns True if the child was live and its exit was confirmed; false otherwise (the id was not live, or the confirmation deadline elapsed)
      */
     stop(id: string): Promise<boolean>;
     /**
-     * Terminate every live child and await their exit.
+     * Terminates every live child and awaits their exit.
      *
      * @returns A promise that resolves after every child stops
      */
     stop(): Promise<void>;
     /**
-     * Stop every child, then destroy the registry emitter last.
+     * Stops every child, then destroys the registry emitter last.
      *
      * @remarks
      * Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
@@ -726,7 +752,8 @@ export declare function readPlatformVariable(environment: Readonly<Record<string
 export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
 
 /**
- * Resolves a command file to the executable path the host would launch.
+ * Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+ * host, which performs its own lookup.
  *
  * @param file - The command executable name or path
  * @param options - The directory searched first and the child's effective environment
@@ -773,29 +800,29 @@ export declare function resolveExecutable(file: string, options?: ExecutableOpti
 export declare class Session implements SessionInterface {
     #private;
     /**
-     * Spawn one child process and begin byte capture.
+     * Spawns one child process and begins byte capture.
      *
      * @param options - Command, workspace, termination, evidence, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
     constructor(options: SessionOptions);
-    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
-    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
     get code(): number | null;
-    /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+    /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
     get signal(): string | null;
-    /** The typed lifecycle observation surface. */
+    /** Holds the typed lifecycle observation surface. */
     get emitter(): EmitterInterface<SessionEventMap>;
-    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    /** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
     get evidence(): string;
-    /** True after the terminal moment arrived and `exit` settled. */
+    /** Reports whether the terminal moment arrived and `exit` settled. */
     get settled(): boolean;
-    /** True after termination began, including after the terminal moment. `end` never turns it true. */
+    /** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
     get stopping(): boolean;
-    /** The child's own ending, awaited without the terminal moment's drain window. */
+    /** Settles at the child's own ending, awaited without the terminal moment's drain window. */
     get ending(): Promise<void>;
-    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
     get exit(): Promise<ProcessExit>;
     /**
      * Writes raw bytes to the open standard-input channel.
@@ -807,7 +834,7 @@ export declare class Session implements SessionInterface {
      * returned promise settles.
      *
      * @param bytes - The payload to write, already framed by the caller
-     * @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`
+     * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
      */
     write(bytes: Uint8Array): Promise<boolean>;
     /**
@@ -827,7 +854,7 @@ export declare class Session implements SessionInterface {
      * @remarks
      * Never rejects, and every call shares one termination bounded by `grace` and `drain`.
      *
-     * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+     * @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
      */
     stop(): Promise<boolean>;
     /**
@@ -880,14 +907,210 @@ export declare function snapshotCommand(command: ProcessCommand): ProcessCommand
  * @param child - The child boundary
  * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
  * @param confirm - The milliseconds the native exit is awaited after the final kill
- * @returns True when the native exit was observed; false when `confirm` elapsed without it
+ * @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
  *
  * @example
  * ```ts
  * const confirmed = await stopChild(child, 5_000, 5_000)
  * ```
  */
-export declare function stopChild(child: ProcessChild, grace: number, confirm: number): Promise<boolean>;
+export declare function stopChild(child: ProcessChildInterface, grace: number, confirm: number): Promise<boolean>;
+
+/**
+ * Supervises one child process and reports each lifecycle moment to the face composing it.
+ *
+ * @remarks
+ * This is the engine every supervised-child face shares. It owns the eager spawn, the byte-bounded
+ * stderr tail and its decoded chunks, the standard-input channel and its bounded confirmation, the
+ * termination sequence, and the progression from the child's native exit through the bounded `drain`
+ * window to one terminal moment. It owns no output framing and no observation surface: a face
+ * attaches its own consumer to `stdout`, frames bytes however its contract promises, and owns the
+ * emitter and event map its consumers subscribe to.
+ *
+ * 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, and `ending`
+ * settles at that same moment. `settled`, `exit`, and `evidence` 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 hands the face its `close` and `terminal` moments before
+ * it destroys stdout and stderr, so a face's own pull surfaces are final while its read ends still
+ * exist.
+ *
+ * The face is a set of callbacks rather than an emitter, because each face publishes a different
+ * event map over the same moments. `chunk` and `fault` carry the live stderr text and the child or
+ * channel faults, `relieve` reports that a termination began so the face can release whatever
+ * backpressure it holds, `close` ends the face's read pipeline at the terminal moment, `terminal`
+ * carries the frozen {@link ProcessExit}, and `teardown` releases the face's own surface after the
+ * termination completes. `relieve` is optional because a face that never pauses the child's output
+ * holds no backpressure to release, and a face with nothing to do there would otherwise declare an
+ * empty method to say so.
+ *
+ * @example
+ * ```ts
+ * import { Supervisor } from '@orkestrel/process/server'
+ *
+ * const engine = new Supervisor(
+ * 	{ command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
+ * 	{
+ * 		chunk: () => undefined,
+ * 		fault: () => undefined,
+ * 		close: () => undefined,
+ * 		terminal: () => undefined,
+ * 		teardown: () => undefined,
+ * 	},
+ * )
+ * const exit = await engine.exit
+ * exit.code // 0
+ * await engine.destroy()
+ * ```
+ */
+export declare class Supervisor {
+    #private;
+    /**
+     * Spawns one child process and begins standard-error capture.
+     *
+     * @remarks
+     * The face's callbacks are captured before anything is read or spawned, so the first moment the
+     * child can produce already has somewhere to go. `options` supplies the command, workspace,
+     * termination, capture, and standard-input settings; a face's own settings, such as an output
+     * retention bound, are read and validated by that face before it constructs this engine, so an
+     * invalid one refuses construction while nothing has been spawned.
+     *
+     * @param options - Command, workspace, termination, capture, and stdin settings
+     * @param face - The composing face's callbacks for each lifecycle moment
+     * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
+     */
+    constructor(options: ProcessOptions, face: SupervisorFace);
+    /** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
+    get stdout(): Readable;
+    /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    get pid(): number | undefined;
+    /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    get code(): number | null;
+    /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+    get signal(): string | null;
+    /** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    get evidence(): string;
+    /** Reports whether the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** Reports whether termination began, including after the terminal moment. */
+    get stopping(): boolean;
+    /**
+     * Settles at the child's own ending, awaited without the terminal moment's drain window.
+     *
+     * @remarks
+     * Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
+     * the host records them. It settles at the native exit, and at the terminal moment for a child
+     * whose spawn produced no native exit at all, so it can never outlive the supervision.
+     */
+    get ending(): Promise<void>;
+    /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit>;
+    /**
+     * Writes raw bytes to the open standard-input channel.
+     *
+     * @remarks
+     * Never rejects, and adds no framing: a face composes whatever terminator its contract promises
+     * before it calls this. `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. After `stop` or `destroy` begins, a later
+     * call settles `false`, because teardown cannot confirm delivery for bytes it is about to
+     * discard.
+     *
+     * @param bytes - The payload to write, already framed by the caller
+     * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
+     *
+     * @example
+     * ```ts
+     * import { Supervisor } from '@orkestrel/process/server'
+     *
+     * const engine = new Supervisor(
+     * 	{
+     * 		command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+     * 		workspace: process.cwd(),
+     * 		writable: true,
+     * 	},
+     * 	{
+     * 		chunk: () => undefined,
+     * 		fault: () => undefined,
+     * 		close: () => undefined,
+     * 		terminal: () => undefined,
+     * 		teardown: () => undefined,
+     * 	},
+     * )
+     * const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
+     * accepted // true
+     * await engine.destroy()
+     * ```
+     */
+    deliver(bytes: Uint8Array): Promise<boolean>;
+    /**
+     * Closes the standard-input channel while leaving the child running.
+     *
+     * @remarks
+     * Never rejects, and terminates nothing: no signal is sent, `stopping` stays false, no drain
+     * window is armed, and the terminal moment does not arrive. The child observes end of input and
+     * decides for itself what to do about it, which is what separates this from `stop`.
+     *
+     * Every call shares one barrier, and it resolves after the host flushes the writes it had already
+     * accepted, or reports that it cannot. A `deliver` after this call resolves `false`, because the
+     * host stops reporting the channel writable the moment it is ended. That same flag keeps the
+     * ended channel quiet for its remaining life, so a later host fault on it settles pending writes
+     * and reaches no face. After `stop` or `destroy` has begun, or after the terminal moment, the
+     * call resolves and changes nothing, because the channel is already being discarded.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    end(): Promise<void>;
+    /**
+     * Terminates the child process tree and reaches the terminal observation moment.
+     *
+     * @remarks
+     * 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 if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Stops the child and releases the composing face after the terminal state freezes.
+     *
+     * @remarks
+     * Always resolves, including when termination was never confirmed. Every call shares one barrier.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Represents the composing face's callbacks for each lifecycle moment of one supervised child.
+ *
+ * @remarks
+ * `Process` and `Session` each construct one and hand it to the supervision engine, which captures
+ * every callback before anything is read or spawned, so the first moment the child can produce
+ * already has somewhere to go. `chunk` receives each decoded standard-error fragment, `fault` the
+ * host error that ended the run, `close` the moment the read channels closed, `terminal` the frozen
+ * exit state, and `teardown` the release of whatever the face still holds. `relieve` is optional
+ * because a face that never pauses the child's output holds no backpressure to release.
+ */
+export declare interface SupervisorFace {
+    /** Receives one decoded standard-error fragment. */
+    readonly chunk: (text: string) => void;
+    /** Receives the host error that ended the run. */
+    readonly fault: (cause: unknown) => void;
+    /** Reports that a termination began, so a face holding output backpressure releases it. */
+    readonly relieve?: () => void;
+    /** Reports that the child's read channels closed. */
+    readonly close: () => void;
+    /** Receives the frozen terminal state. */
+    readonly terminal: (exit: ProcessExit) => void;
+    /** Releases whatever the face still holds after the terminal moment. */
+    readonly teardown: () => void;
+}
 
 /**
  * Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
@@ -1036,14 +1259,14 @@ export declare function validateWorkspace(workspace: string | undefined): void;
  *
  * @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
+ * @returns True if 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>;
+export declare function waitForClose(child: Pick<ProcessChildInterface, 'once' | 'off'>, timeout: number): Promise<boolean>;
 
 /**
  * Waits for one child process's native exit, bounded by a deadline.
@@ -1057,6 +1280,6 @@ export declare function waitForClose(child: Pick<ProcessChild, 'once' | 'off'>,
  * await waitForExit(child, 5_000)
  * ```
  */
-export declare function waitForExit(child: Pick<ProcessChild, 'exitCode' | 'signalCode' | 'once' | 'off'>, timeout: number): Promise<void>;
+export declare function waitForExit(child: Pick<ProcessChildInterface, 'exitCode' | 'signalCode' | 'once' | 'off'>, timeout: number): Promise<void>;
 
 export { }