@orkestrel/process 0.0.7 → 0.0.9

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

@@ -5,10 +5,8 @@ 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 { ProcessInterface } from '@orkestrel/process';
@@ -16,6 +14,9 @@ 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';
 
 /**
@@ -117,6 +118,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.
  *
@@ -151,6 +176,25 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
  */
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
+/**
+ * Creates one raw byte session over a supervised child process.
+ *
+ * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+ * @returns The launched {@link SessionInterface}
+ *
+ * @example
+ * ```ts
+ * import { createSession } from '@orkestrel/process/server'
+ *
+ * const session = createSession({
+ * 	command: { file: 'node', arguments: ['server.js', '--stdio'] },
+ * 	workspace: process.cwd(),
+ * 	grace: 5000,
+ * })
+ * ```
+ */
+export declare function createSession(options: SessionOptions): SessionInterface;
+
 /**
  * Spawns one command as a detached process and returns without waiting for it.
  *
@@ -170,7 +214,7 @@ export declare function createProcessManager(options?: ProcessManagerOptions): P
  * 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.
@@ -179,7 +223,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
@@ -205,7 +251,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.
@@ -231,7 +277,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.
@@ -694,45 +740,105 @@ 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.
+ * Supervises one child and publishes its standard output as raw bytes.
+ *
+ * @remarks
+ * This is the transport face of the supervision engine `Process` also composes. It frames nothing,
+ * retains nothing, and decodes nothing on the output side: every chunk the host delivers becomes one
+ * `stdout` event carrying that chunk's bytes, in arrival order, so a consumer speaking a
+ * length-prefixed or delimiter-framed protocol reads exactly what the child wrote and frames it
+ * itself. Standard error is decoded and forwarded as `stderr`, with the same byte-bounded `evidence`
+ * tail a `Process` retains, because a diagnostic stream is read rather than parsed.
+ *
+ * Each emitted chunk is this session's own copy, and a plain `Uint8Array` rather than the host buffer
+ * the read produced, so a consumer keeps it, mutates it, concatenates it, and reads its whole backing
+ * buffer without reaching memory the host still manages and without depending on a host type.
+ *
+ * The standard-input channel is open from the spawn, and `end` closes it without terminating
+ * anything. That is the member a cooperative protocol reaches for: the child observes end of input
+ * and exits on its own, which `ending` reports. `stop` and `destroy` remain the terminations, and
+ * `exit` remains the terminal moment — the native exit plus at most `drain` while a descendant holds
+ * the inherited read ends.
  *
  * @example
  * ```ts
- * const retention = new Retention()
- * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
- * retention.retained // 3
+ * import { Session } from '@orkestrel/process/server'
+ *
+ * const session = new Session({
+ * 	command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+ * 	workspace: process.cwd(),
+ * })
  * ```
  */
-export declare class Retention implements RetentionInterface {
+export declare class Session implements SessionInterface {
     #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.
+     * Spawn one child process and begin byte capture.
      *
-     * @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
+     * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+     * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    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;
+    constructor(options: SessionOptions);
+    /** 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. */
+    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. */
+    get signal(): string | null;
+    /** The typed lifecycle observation surface. */
+    get emitter(): EmitterInterface<SessionEventMap>;
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    get evidence(): string;
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after 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. */
+    get ending(): Promise<void>;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit>;
     /**
-     * Retains a delivered chunk within a byte limit.
+     * Writes raw bytes to the open standard-input channel.
      *
-     * @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
+     * @remarks
+     * Never rejects, and appends no terminator: the child receives exactly these bytes. `true` means
+     * the host accepted them without reporting a fault; it does not prove that the child read them.
+     * The channel can queue the payload, so treat the array as owned by the channel until the
+     * 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`
+     */
+    write(bytes: Uint8Array): Promise<boolean>;
+    /**
+     * Closes the standard-input channel and leaves the child running.
+     *
+     * @remarks
+     * Never rejects and terminates nothing: `stopping` stays false and the terminal moment does not
+     * arrive. Every call shares one barrier, which resolves after the host flushes the writes it had
+     * already accepted. A later `write` resolves `false`.
+     *
+     * @returns The stable barrier shared by every call
      */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
+    end(): Promise<void>;
+    /**
+     * Terminates the child process tree and reaches the terminal observation moment.
+     *
+     * @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
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Stops the child and destroys the observation emitter 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>;
 }
 
 /**
@@ -787,9 +893,12 @@ export declare function stopChild(child: ProcessChild, grace: number, confirm: n
  * 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

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

@@ -5,10 +5,8 @@ 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 { ProcessInterface } from '@orkestrel/process';
@@ -16,6 +14,9 @@ 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';
 
 /**
@@ -117,6 +118,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.
  *
@@ -151,6 +176,25 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
  */
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
+/**
+ * Creates one raw byte session over a supervised child process.
+ *
+ * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+ * @returns The launched {@link SessionInterface}
+ *
+ * @example
+ * ```ts
+ * import { createSession } from '@orkestrel/process/server'
+ *
+ * const session = createSession({
+ * 	command: { file: 'node', arguments: ['server.js', '--stdio'] },
+ * 	workspace: process.cwd(),
+ * 	grace: 5000,
+ * })
+ * ```
+ */
+export declare function createSession(options: SessionOptions): SessionInterface;
+
 /**
  * Spawns one command as a detached process and returns without waiting for it.
  *
@@ -170,7 +214,7 @@ export declare function createProcessManager(options?: ProcessManagerOptions): P
  * 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.
@@ -179,7 +223,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
@@ -205,7 +251,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.
@@ -231,7 +277,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.
@@ -694,45 +740,105 @@ 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.
+ * Supervises one child and publishes its standard output as raw bytes.
+ *
+ * @remarks
+ * This is the transport face of the supervision engine `Process` also composes. It frames nothing,
+ * retains nothing, and decodes nothing on the output side: every chunk the host delivers becomes one
+ * `stdout` event carrying that chunk's bytes, in arrival order, so a consumer speaking a
+ * length-prefixed or delimiter-framed protocol reads exactly what the child wrote and frames it
+ * itself. Standard error is decoded and forwarded as `stderr`, with the same byte-bounded `evidence`
+ * tail a `Process` retains, because a diagnostic stream is read rather than parsed.
+ *
+ * Each emitted chunk is this session's own copy, and a plain `Uint8Array` rather than the host buffer
+ * the read produced, so a consumer keeps it, mutates it, concatenates it, and reads its whole backing
+ * buffer without reaching memory the host still manages and without depending on a host type.
+ *
+ * The standard-input channel is open from the spawn, and `end` closes it without terminating
+ * anything. That is the member a cooperative protocol reaches for: the child observes end of input
+ * and exits on its own, which `ending` reports. `stop` and `destroy` remain the terminations, and
+ * `exit` remains the terminal moment — the native exit plus at most `drain` while a descendant holds
+ * the inherited read ends.
  *
  * @example
  * ```ts
- * const retention = new Retention()
- * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
- * retention.retained // 3
+ * import { Session } from '@orkestrel/process/server'
+ *
+ * const session = new Session({
+ * 	command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+ * 	workspace: process.cwd(),
+ * })
  * ```
  */
-export declare class Retention implements RetentionInterface {
+export declare class Session implements SessionInterface {
     #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.
+     * Spawn one child process and begin byte capture.
      *
-     * @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
+     * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+     * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    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;
+    constructor(options: SessionOptions);
+    /** 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. */
+    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. */
+    get signal(): string | null;
+    /** The typed lifecycle observation surface. */
+    get emitter(): EmitterInterface<SessionEventMap>;
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    get evidence(): string;
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after 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. */
+    get ending(): Promise<void>;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit>;
     /**
-     * Retains a delivered chunk within a byte limit.
+     * Writes raw bytes to the open standard-input channel.
      *
-     * @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
+     * @remarks
+     * Never rejects, and appends no terminator: the child receives exactly these bytes. `true` means
+     * the host accepted them without reporting a fault; it does not prove that the child read them.
+     * The channel can queue the payload, so treat the array as owned by the channel until the
+     * 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`
+     */
+    write(bytes: Uint8Array): Promise<boolean>;
+    /**
+     * Closes the standard-input channel and leaves the child running.
+     *
+     * @remarks
+     * Never rejects and terminates nothing: `stopping` stays false and the terminal moment does not
+     * arrive. Every call shares one barrier, which resolves after the host flushes the writes it had
+     * already accepted. A later `write` resolves `false`.
+     *
+     * @returns The stable barrier shared by every call
      */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
+    end(): Promise<void>;
+    /**
+     * Terminates the child process tree and reaches the terminal observation moment.
+     *
+     * @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
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Stops the child and destroys the observation emitter 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>;
 }
 
 /**
@@ -787,9 +893,12 @@ export declare function stopChild(child: ProcessChild, grace: number, confirm: n
  * 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