@orkestrel/process 0.0.8 → 0.0.10

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

@@ -5,20 +5,26 @@ import { ExecutableOptions } from '@orkestrel/process';
 import { ExecuteInput } from '@orkestrel/process';
 import { ExecuteOptions } from '@orkestrel/process';
 import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteResult as ExecuteResult_2 } from '@orkestrel/process';
 import { ExecuteSyncOptions } from '@orkestrel/process';
 import { ProcessCommand } from '@orkestrel/process';
-import { ProcessCommand as ProcessCommand_2 } from '@orkestrel/process';
 import { ProcessEventMap } from '@orkestrel/process';
 import { ProcessExit } from '@orkestrel/process';
+import { ProcessExit as ProcessExit_2 } from '@orkestrel/process';
 import { ProcessInterface } from '@orkestrel/process';
+import { ProcessInterface as ProcessInterface_2 } from '@orkestrel/process';
 import { ProcessManagerEventMap } from '@orkestrel/process';
 import { ProcessManagerInterface } from '@orkestrel/process';
+import { ProcessManagerInterface as ProcessManagerInterface_2 } from '@orkestrel/process';
 import { ProcessManagerOptions } from '@orkestrel/process';
+import { ProcessManagerOptions as ProcessManagerOptions_2 } from '@orkestrel/process';
 import { ProcessOptions } from '@orkestrel/process';
+import { ProcessOptions as ProcessOptions_2 } from '@orkestrel/process';
+import { Readable } from 'node:stream';
 import { SessionEventMap } from '@orkestrel/process';
 import { SessionInterface } from '@orkestrel/process';
+import { SessionInterface as SessionInterface_2 } from '@orkestrel/process';
 import { SessionOptions } from '@orkestrel/process';
+import { SessionOptions as SessionOptions_2 } from '@orkestrel/process';
 import { SpawnInput } from '@orkestrel/process';
 
 /**
@@ -120,6 +126,30 @@ export declare function buildPlatformSpawn(command: ProcessCommand, file: string
  */
 export declare function buildSpawn(command: ProcessCommand, options?: ExecutableOptions): SpawnInput;
 
+/**
+ * Bounds one delivered stream chunk to the bytes a capture still has room for.
+ *
+ * @remarks
+ * A chunk that is not a buffer contributes nothing and reports `undefined` rather than throwing,
+ * because a stream `data` listener receives an `unknown` payload. The cut is byte-exact and might
+ * land inside a multibyte sequence, because {@link buildExecuteResult} performs the single
+ * code-point-boundary trim over the whole capture rather than over each chunk. Give the capture one
+ * byte more room than its limit, so that final trim can read the first excluded byte and retreat off
+ * a split sequence. A chunk that fits its room is returned as the delivered buffer itself rather
+ * than a copy, because a capture appending it copies again and never writes through it; a chunk that
+ * overruns its room returns a copy of the bytes that fit. Treat the return as read-only either way.
+ *
+ * @param chunk - The delivered chunk, ignored when it is not a buffer
+ * @param room - The bytes the capture still accepts
+ * @returns The bytes to retain, or `undefined` when the chunk contributes none
+ *
+ * @example
+ * ```ts
+ * captureChunk(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
+ * ```
+ */
+export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
+
 /**
  * Creates one supervised child process.
  *
@@ -192,7 +222,7 @@ export declare function createSession(options: SessionOptions): SessionInterface
  * detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function detach(command: ProcessCommand_2, options?: DetachOptions): void;
+export declare function detach(command: ProcessCommand, options?: DetachOptions): void;
 
 /**
  * Runs one command to completion, buffering its output, and settles with the outcome.
@@ -201,7 +231,9 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * The executable is resolved through {@link buildSpawn}, so no run uses a shell. On a POSIX host the
  * child is detached, which is what lets its whole process group be terminated. Standard output and
  * error are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}) and `truncated` reports
- * whether either stream exceeded it. A positive `timeout` and an aborting `signal` both terminate the
+ * whether either stream exceeded it. Each capture keeps one byte beyond `limit`, so the single
+ * code-point-boundary trim in {@link buildExecuteResult} reads the first excluded byte and never
+ * delivers a split multibyte sequence. A positive `timeout` and an aborting `signal` both terminate the
  * child through the same bounded stop, and only the earliest is recorded: a timeout reports
  * `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
  * a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
@@ -227,7 +259,7 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * const result = await execute({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function execute(command: ProcessCommand_2, options?: ExecuteOptions): Promise<ExecuteResult_2>;
+export declare function execute(command: ProcessCommand, options?: ExecuteOptions): Promise<ExecuteResult>;
 
 /**
  * Runs one command to completion synchronously, buffering its output, and returns the outcome.
@@ -253,7 +285,7 @@ export declare function execute(command: ProcessCommand_2, options?: ExecuteOpti
  * const result = executeSync({ file: 'git', arguments: ['--version'] }, { strict: false })
  * ```
  */
-export declare function executeSync(command: ProcessCommand_2, options?: ExecuteSyncOptions): ExecuteResult_2;
+export declare function executeSync(command: ProcessCommand, options?: ExecuteSyncOptions): ExecuteResult;
 
 /**
  * Renders one command into its diagnostic command line.
@@ -277,14 +309,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.
@@ -294,7 +326,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
@@ -323,7 +355,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`.
@@ -337,7 +369,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
@@ -414,37 +446,37 @@ export declare function mergePlatformEnvironment(platform: NodeJS.Platform, pare
  * await child.destroy()
  * ```
  */
-export declare class Process implements ProcessInterface {
+export declare class Process implements ProcessInterface_2 {
     #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. */
+    constructor(options: ProcessOptions_2);
+    /** 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. */
-    get exit(): Promise<ProcessExit>;
+    /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit_2>;
     /**
-     * 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
@@ -458,7 +490,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>;
     /**
@@ -470,7 +502,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>;
     /**
@@ -485,15 +517,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
@@ -507,30 +531,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
@@ -539,12 +575,19 @@ 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.
+ * Represents a keyed registry of live supervised child processes.
  *
  * @remarks
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -572,33 +615,33 @@ export declare interface ProcessChild {
  * await manager.destroy()
  * ```
  */
-export declare class ProcessManager implements ProcessManagerInterface {
+export declare class ProcessManager implements ProcessManagerInterface_2 {
     #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. */
+    constructor(options?: ProcessManagerOptions_2);
+    /** 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;
+    process(id: string): ProcessInterface_2 | undefined;
     /**
-     * A snapshot of every live child.
+     * Returns a snapshot of every live child.
      *
      * @returns The live children in launch order
      */
-    processes(): readonly ProcessInterface[];
+    processes(): readonly ProcessInterface_2[];
     /**
-     * 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
@@ -614,29 +657,29 @@ export declare class ProcessManager implements ProcessManagerInterface {
      * @returns The launched child
      * @throws A {@link ProcessError} coded `duplicate` when `id` is already live, `protocol` when the registry is being destroyed, or `invalid` when an option or command string is malformed
      */
-    launch(id: string, options: ProcessOptions): ProcessInterface;
+    launch(id: string, options: ProcessOptions_2): ProcessInterface_2;
     /**
-     * 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
@@ -715,48 +758,6 @@ export declare function readVariable(environment: Readonly<Record<string, string
  */
 export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
 
-/**
- * Accumulates byte totals while retaining a bounded stream head.
- *
- * @example
- * ```ts
- * const retention = new Retention()
- * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
- * retention.retained // 3
- * ```
- */
-export declare class Retention implements RetentionInterface {
-    #private;
-    /** The bytes delivered by the stream. */
-    get delivered(): number;
-    /** The bytes retained from the stream head. */
-    get retained(): number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
-/** Exposes byte totals and bounded stream-head retention. */
-export declare interface RetentionInterface {
-    /** The bytes delivered by the stream. */
-    readonly delivered: number;
-    /** The bytes retained from the stream head. */
-    readonly retained: number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
 /**
  * Supervises one child and publishes its standard output as raw bytes.
  *
@@ -788,33 +789,33 @@ export declare interface RetentionInterface {
  * })
  * ```
  */
-export declare class Session implements SessionInterface {
+export declare class Session implements SessionInterface_2 {
     #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. */
+    constructor(options: SessionOptions_2);
+    /** 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. */
-    get exit(): Promise<ProcessExit>;
+    /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit_2>;
     /**
      * Writes raw bytes to the open standard-input channel.
      *
@@ -825,7 +826,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>;
     /**
@@ -845,7 +846,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>;
     /**
@@ -898,22 +899,221 @@ 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_2, 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_2>;
+    /**
+     * 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.
  *
  * @remarks
- * Keeps the head — the captured start of a one-shot run's output. When the cut point lands inside
- * a multibyte sequence, the end retreats to the sequence's start so the retained bytes always end
- * on a code-point boundary and decode without a replacement character.
+ * Keeps the head — the captured start of a one-shot run's output. The end retreats only when a
+ * sequence genuinely spans the cut: the byte at `limit` carries the continuation bit pattern, and a
+ * lead byte within the preceding three bytes declares a length that reaches it. The retained bytes
+ * then end on a code-point boundary and decode without a replacement character. A byte at `limit`
+ * that carries the continuation pattern without such a lead byte is invalid UTF-8 rather than a
+ * split sequence, so the full `limit` survives instead of a valid byte being dropped for it.
  *
  * @param bytes - The accumulated bytes
  * @param limit - The maximum retained byte count
@@ -1051,14 +1251,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.
@@ -1072,6 +1272,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 { }