@orkestrel/process 0.0.6 → 0.0.8

package/dist/src/server/index.js

@@ -6,8 +6,8 @@ import { platform } from "node:process";
 import { boundsOf, holds, isNonEmptyString, isNonNegativeInteger, isString } from "@orkestrel/contract";
 import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
 import { createInterface } from "node:readline";
-import { StringDecoder } from "node:string_decoder";
 import { Emitter } from "@orkestrel/emitter";
+import { StringDecoder } from "node:string_decoder";
 //#region src/server/helpers.ts
 /**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -692,87 +692,92 @@ function buildExecuteResult(input) {
 	});
 }
 //#endregion
-//#region src/server/Process.ts
+//#region src/server/Supervisor.ts
 /**
-* Supervises one child while keeping every observation channel aligned at termination.
+* Supervises one child process and reports each lifecycle moment to the face composing it.
 *
 * @remarks
-* The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
-* the host child directly, so they expose native exit as soon as the host records it. `settled`,
-* `exit`, `evidence`, and `lines` reach one terminal moment after the read channels close or the
-* bounded `drain` window cuts them off. That window is armed by the child's native exit and by a
-* termination this package initiated, so every way a child can end reaches the moment. The terminal
-* routine freezes `evidence` and ends `lines` before it destroys stdout, stderr, or the emitter, so
-* the push channel never disappears while a pull channel can still change or wait indefinitely.
-*
-* Standard output is framed through `readline` into a single-consumer stream. Lines already framed
-* and queued remain available through the terminal moment, while bytes arriving after a requested
-* termination may be cut off. Standard error is forwarded through the live `stderr` event and
-* retained as a byte-bounded raw tail until that same moment. `stop` ends the child tree and the
-* observation surfaces. `destroy` performs that stop and then destroys the emitter after the
-* frozen terminal state exists.
-*
-* @example
-* ```ts
-* import { Process } from '@orkestrel/process/server'
-*
-* const child = new Process({
-* 	command: { file: 'node', arguments: ['--version'] },
-* 	workspace: process.cwd(),
-* })
-* const exit = await child.exit
-* await child.destroy()
-* ```
+* 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.
 */
-var Process = class {
-	#emitter;
+var Supervisor = class {
+	#chunk;
+	#fault;
+	#relieve;
+	#close;
+	#terminal;
+	#teardown;
 	#child;
-	#reader;
 	#grace;
 	#drain;
 	#evidence;
-	#backlog;
 	#delivery;
 	#decoder = new StringDecoder("utf8");
 	#exit = Promise.withResolvers();
-	#lines;
-	#queue = [];
-	#waiters = [];
+	#ending = Promise.withResolvers();
 	#signal;
 	#abort;
 	#writes = /* @__PURE__ */ new Map();
 	#tail = Buffer.alloc(0);
-	#head = 0;
-	#pending = 0;
-	#requested = false;
-	#paused = false;
-	#truncated = false;
 	#stopping = false;
 	#settled = false;
-	#ended = false;
 	#input = 0;
 	#failure;
 	#waiting;
+	#closure;
 	#termination;
-	#ending;
+	#destruction;
 	/**
-	* Spawn one child process and begin stream capture.
+	* Spawn one child process and begin standard-error capture.
 	*
-	* @param options - Command, workspace, termination, capture, stdin, and observation settings
+	* @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) {
+	constructor(options, face) {
+		this.#chunk = face.chunk;
+		this.#fault = face.fault;
+		this.#relieve = face.relieve;
+		this.#close = face.close;
+		this.#terminal = face.terminal;
+		this.#teardown = face.teardown;
 		const source = options.command;
 		const workspace = options.workspace;
 		const grace = options.grace;
 		const drain = options.drain;
 		const evidence = options.evidence;
-		const backlog = options.backlog;
 		const delivery = options.delivery;
 		const writable = options.writable;
 		const signal = options.signal;
-		const on = options.on;
-		const error = options.error;
 		const command = snapshotCommand(source);
 		const input = command.input;
 		validateCommand(command);
@@ -781,18 +786,11 @@ var Process = class {
 		validateTimer(drain, "option 'drain'");
 		validateTimer(delivery, "option 'delivery'");
 		validateBytes(evidence, "option 'evidence'", 0);
-		validateBytes(backlog, "option 'backlog'", 1);
-		this.#emitter = new Emitter({
-			...on === void 0 ? {} : { on },
-			...error === void 0 ? {} : { error }
-		});
 		this.#grace = grace ?? PROCESS_GRACE;
 		this.#drain = drain ?? PROCESS_DRAIN;
 		this.#evidence = evidence ?? PROCESS_EVIDENCE;
-		this.#backlog = backlog ?? PROCESS_BACKLOG;
 		this.#delivery = delivery ?? 0;
 		this.#signal = signal;
-		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
 		const childEnvironment = mergeEnvironment(command.isolated === true, command.environment);
 		const plan = buildSpawn(command, {
 			workspace,
@@ -810,16 +808,10 @@ var Process = class {
 			windowsHide: true,
 			windowsVerbatimArguments: plan.verbatim
 		});
-		this.#reader = createInterface({
-			input: this.#child.stdout,
-			crlfDelay: Infinity
-		});
-		this.#reader.on("line", this.#push.bind(this));
-		this.#reader.once("close", this.#finish.bind(this));
-		this.#child.once("error", (cause) => this.#emitter.emit("error", cause));
+		this.#child.once("error", this.#fault);
 		this.#child.once("exit", this.#expire.bind(this));
-		this.#child.once("close", this.#close.bind(this));
-		this.#child.stdin.on("error", (cause) => this.#failInputStream(cause));
+		this.#child.once("close", this.#complete.bind(this));
+		this.#child.stdin.on("error", this.#failInputStream.bind(this));
 		this.#child.stderr.on("data", this.#retain.bind(this));
 		if (input !== void 0) {
 			this.#input += 1;
@@ -835,6 +827,10 @@ var Process = class {
 			if (signal.aborted) this.stop();
 		}
 	}
+	/** The child's standard-output stream, for the composing face to attach its own consumer to. */
+	get stdout() {
+		return this.#child.stdout;
+	}
 	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#child.pid;
@@ -847,22 +843,10 @@ var Process = class {
 	get signal() {
 		return this.#child.signalCode;
 	}
-	/** The typed lifecycle observation surface. */
-	get emitter() {
-		return this.#emitter;
-	}
-	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
-	get lines() {
-		return this.#lines;
-	}
 	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#tail.toString("utf8");
 	}
-	/** True when the `lines` stream omitted output after a retention bound was reached. */
-	get truncated() {
-		return this.#truncated;
-	}
 	/** True after the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#settled;
@@ -871,34 +855,43 @@ var Process = class {
 	get stopping() {
 		return this.#stopping;
 	}
+	/**
+	* 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() {
+		return this.#ending.promise;
+	}
 	/** The terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#exit.promise;
 	}
 	/**
-	* Write one line to the open standard-input channel.
+	* Writes raw bytes to the open standard-input channel.
 	*
 	* @remarks
-	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
-	* prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
-	* full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
-	* terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
-	* 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
-	* the write can settle `true` without a callback error or a stream error while the child remains
-	* alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
-	* that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
-	* for bytes the package is about to discard.
+	* 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 text - The line text without its trailing newline
+	* @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`
 	*/
-	send(text) {
+	deliver(bytes) {
 		const stdin = this.#child.stdin;
 		if (this.#settled || this.#stopping || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
 		const settled = Promise.withResolvers();
 		this.#writes.set(settled, void 0);
 		try {
-			stdin.write(`${text}\n`, this.#confirmWrite.bind(this, settled));
+			stdin.write(bytes, this.#confirmWrite.bind(this, settled));
 		} catch {
 			this.#settleWrite(settled, false);
 			return settled.promise;
@@ -911,6 +904,28 @@ var Process = class {
 		return settled.promise;
 	}
 	/**
+	* 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() {
+		if (this.#closure !== void 0) return this.#closure;
+		this.#closure = this.#endInput();
+		return this.#closure;
+	}
+	/**
 	* Terminates the child process tree and reaches the terminal observation moment.
 	*
 	* @remarks
@@ -927,7 +942,7 @@ var Process = class {
 		return this.#termination;
 	}
 	/**
-	* Stops the child and destroys the observation emitter after the terminal state freezes.
+	* 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.
@@ -935,95 +950,22 @@ var Process = class {
 	* @returns The stable barrier shared by every call
 	*/
 	destroy() {
-		if (this.#ending !== void 0) return this.#ending;
-		this.#ending = this.#end();
-		return this.#ending;
-	}
-	#iterate() {
-		this.#requested = true;
-		return Object.freeze({ next: this.#next.bind(this) });
-	}
-	#next() {
-		const line = this.#take();
-		if (line !== void 0) return Promise.resolve(Object.freeze({
-			done: false,
-			value: line
-		}));
-		if (this.#ended) return Promise.resolve(Object.freeze({
-			done: true,
-			value: void 0
-		}));
-		const waiter = Promise.withResolvers();
-		this.#waiters.push(waiter);
-		return waiter.promise;
-	}
-	#take() {
-		if (this.#head >= this.#queue.length) return void 0;
-		const line = this.#queue[this.#head];
-		this.#queue[this.#head] = "";
-		this.#head += 1;
-		if (this.#head >= this.#queue.length) {
-			this.#queue.length = 0;
-			this.#head = 0;
-		}
-		if (line === void 0) return void 0;
-		this.#pending -= Buffer.byteLength(line) + 1;
-		this.#relieve();
-		return line;
-	}
-	#push(line) {
-		if (this.#ended) return;
-		const waiter = this.#waiters.shift();
-		if (waiter !== void 0) {
-			waiter.resolve(Object.freeze({
-				done: false,
-				value: line
-			}));
-			return;
-		}
-		const bytes = Buffer.byteLength(line) + 1;
-		const limit = this.#stopping ? this.#backlog * 2 : this.#backlog;
-		if ((!this.#requested || this.#stopping) && this.#pending + bytes > limit) {
-			this.#truncated = true;
-			return;
-		}
-		this.#queue.push(line);
-		this.#pending += bytes;
-		this.#restrain();
-	}
-	#restrain() {
-		if (this.#paused || this.#stopping || !this.#requested) return;
-		if (this.#pending < this.#backlog) return;
-		this.#paused = true;
-		this.#reader.pause();
-	}
-	#relieve() {
-		if (!this.#paused || this.#ended) return;
-		if (!this.#stopping && this.#pending > this.#backlog / 2) return;
-		this.#paused = false;
-		this.#reader.resume();
-	}
-	#finish() {
-		if (this.#ended) return;
-		this.#ended = true;
-		this.#paused = false;
-		for (const waiter of this.#waiters) waiter.resolve(Object.freeze({
-			done: true,
-			value: void 0
-		}));
-		this.#waiters.length = 0;
+		if (this.#destruction !== void 0) return this.#destruction;
+		this.#destruction = this.#conclude();
+		return this.#destruction;
 	}
 	#retain(chunk) {
 		if (!Buffer.isBuffer(chunk) || this.#settled) return;
 		this.#tail = trimTail(Buffer.concat([this.#tail, chunk]), this.#evidence);
 		const text = this.#decoder.write(chunk);
-		if (text.length > 0) this.#emitter.emit("stderr", text);
+		if (text.length > 0) this.#chunk(text);
 	}
-	#close() {
+	#complete() {
 		if (this.#settled) return;
 		this.#settle(true);
 	}
 	#expire() {
+		this.#ending.resolve();
 		if (this.#settled) return;
 		this.#wait();
 	}
@@ -1035,17 +977,18 @@ var Process = class {
 	}
 	#settle(drained) {
 		const suffix = this.#decoder.end();
-		if (suffix.length > 0) this.#emitter.emit("stderr", suffix);
+		if (suffix.length > 0) this.#chunk(suffix);
 		this.#settled = true;
 		this.#removeAbortListener();
-		this.#reader.close();
+		this.#close();
 		const exit = Object.freeze({
 			code: this.code,
 			signal: this.signal,
 			drained
 		});
 		this.#exit.resolve(exit);
-		this.#emitter.emit("exit", exit);
+		this.#ending.resolve();
+		this.#terminal(exit);
 		this.#child.stdout.destroy();
 		this.#child.stderr.destroy();
 	}
@@ -1066,6 +1009,13 @@ var Process = class {
 	#completeInput() {
 		this.#input -= 1;
 	}
+	#endInput() {
+		const stdin = this.#child.stdin;
+		if (this.#stopping || this.#settled || stdin.writableEnded || stdin.destroyed) return Promise.resolve();
+		const ended = Promise.withResolvers();
+		stdin.end(() => ended.resolve());
+		return ended.promise;
+	}
 	#settleWrite(settled, accepted) {
 		if (!this.#writes.has(settled)) return;
 		const timer = this.#writes.get(settled);
@@ -1077,34 +1027,28 @@ var Process = class {
 		for (const settled of this.#writes.keys()) this.#settleWrite(settled, false);
 	}
 	#failInputStream(cause) {
-		if (this.#child.stdin.writableEnded || this.#input > 0) {
+		if (this.#input > 0) {
 			this.#settleWrites();
 			return;
 		}
 		this.#failInputCallback(cause);
 	}
 	#failInputCallback(cause) {
+		if (this.#child.stdin.writableEnded) {
+			this.#settleWrites();
+			return;
+		}
 		if (this.#failure !== void 0 || this.#stopping) return;
 		this.#failure = cause;
 		this.#settleWrites();
-		this.#emitter.emit("error", new ProcessError("The standard-input channel failed", {
+		this.#fault(new ProcessError("The standard-input channel failed", {
 			code: "protocol",
 			cause
 		}));
 	}
-	#capBacklog() {
-		const limit = this.#backlog * 2;
-		while (this.#pending > limit && this.#queue.length > this.#head) {
-			const line = this.#queue.pop();
-			if (line === void 0) break;
-			this.#pending -= Buffer.byteLength(line) + 1;
-			this.#truncated = true;
-		}
-	}
 	async #kill() {
 		this.#stopping = true;
-		this.#capBacklog();
-		this.#relieve();
+		this.#relieve?.();
 		const confirmed = await stopChild(this.#child, this.#grace, PROCESS_CONFIRMATION);
 		this.#settleWrites();
 		this.#child.stdin.destroy();
@@ -1112,54 +1056,343 @@ var Process = class {
 		if (!this.#settled) this.#settle(false);
 		return confirmed;
 	}
-	async #end() {
+	async #conclude() {
 		await this.stop();
-		this.#emitter.destroy();
+		this.#teardown();
 	}
 };
 //#endregion
-//#region src/server/ProcessManager.ts
+//#region src/server/Process.ts
 /**
-* A keyed registry of live supervised child processes.
+* Supervises one child while keeping every observation channel aligned at termination.
 *
 * @remarks
-* A child launched under an id joins the registry and emits `launch`; when it settles it removes
-* itself and emits `exit`, so `count` and `processes` reflect only live children. The id is reserved
-* before the child is constructed and released when construction throws, so a refused launch never
-* strands its key. Eviction follows the child's own `exit` promise, which no listener can forge, so
-* it lands one microtask after the child's public `exit` event: a listener on that event still sees
-* the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
-* and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
-* getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
-* `exit`, never from `launch`. `destroy` awaits every child's own teardown, including the teardown
-* of a child a lost race refused, which destroys each child's observation emitter and leaves every
-* subscription on it silently inert, then destroys the registry emitter last.
+* The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
+* the host child directly, so they expose native exit as soon as the host records it. `settled`,
+* `exit`, `evidence`, and `lines` reach one terminal moment after the read channels close or the
+* bounded `drain` window cuts them off. That window is armed by the child's native exit and by a
+* termination this package initiated, so every way a child can end reaches the moment. The terminal
+* routine freezes `evidence` and ends `lines` before it destroys stdout, stderr, or the emitter, so
+* the push channel never disappears while a pull channel can still change or wait indefinitely.
+*
+* Standard output is framed through `readline` into a single-consumer stream. Lines already framed
+* and queued remain available through the terminal moment, while bytes arriving after a requested
+* termination may be cut off. Standard error is forwarded through the live `stderr` event and
+* retained as a byte-bounded raw tail until that same moment. `stop` ends the child tree and the
+* observation surfaces. `destroy` performs that stop and then destroys the emitter after the
+* frozen terminal state exists.
 *
 * @example
 * ```ts
-* import { ProcessManager } from '@orkestrel/process/server'
+* import { Process } from '@orkestrel/process/server'
 *
-* const manager = new ProcessManager()
-* const child = manager.launch('build', {
-* 	command: { file: 'node', arguments: ['build.js'] },
+* const child = new Process({
+* 	command: { file: 'node', arguments: ['--version'] },
 * 	workspace: process.cwd(),
 * })
-* await child.exit
-* await manager.destroy()
+* const exit = await child.exit
+* await child.destroy()
 * ```
 */
-var ProcessManager = class {
+var Process = class {
 	#emitter;
-	#children = /* @__PURE__ */ new Map();
-	#ids = /* @__PURE__ */ new Set();
-	#orphans = /* @__PURE__ */ new Set();
-	#destroying = false;
-	#ending;
+	#engine;
+	#reader;
+	#backlog;
+	#lines;
+	#queue = [];
+	#waiters = [];
+	#head = 0;
+	#pending = 0;
+	#requested = false;
+	#paused = false;
+	#truncated = false;
+	#ended = false;
 	/**
-	* Construct a process registry.
+	* Spawn one child process and begin stream capture.
 	*
-	* @param options - Initial fleet-level observation hooks and listener-error handling
-	*/
+	* @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) {
+		const source = options.command;
+		const workspace = options.workspace;
+		const grace = options.grace;
+		const drain = options.drain;
+		const evidence = options.evidence;
+		const backlog = options.backlog;
+		const delivery = options.delivery;
+		const writable = options.writable;
+		const signal = options.signal;
+		const on = options.on;
+		const error = options.error;
+		const command = snapshotCommand(source);
+		validateCommand(command);
+		validateWorkspace(workspace);
+		validateTimer(grace, "option 'grace'");
+		validateTimer(drain, "option 'drain'");
+		validateTimer(delivery, "option 'delivery'");
+		validateBytes(evidence, "option 'evidence'", 0);
+		validateBytes(backlog, "option 'backlog'", 1);
+		this.#emitter = new Emitter({
+			...on === void 0 ? {} : { on },
+			...error === void 0 ? {} : { error }
+		});
+		this.#backlog = backlog ?? PROCESS_BACKLOG;
+		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
+		this.#engine = new Supervisor({
+			command,
+			workspace,
+			...grace === void 0 ? {} : { grace },
+			...drain === void 0 ? {} : { drain },
+			...evidence === void 0 ? {} : { evidence },
+			...delivery === void 0 ? {} : { delivery },
+			...writable === void 0 ? {} : { writable },
+			...signal === void 0 ? {} : { signal }
+		}, {
+			chunk: this.#reportStderr.bind(this),
+			fault: this.#reportFault.bind(this),
+			relieve: this.#releaseBackpressure.bind(this),
+			close: this.#closeReader.bind(this),
+			terminal: this.#reportExit.bind(this),
+			teardown: this.#emitter.destroy.bind(this.#emitter)
+		});
+		this.#reader = createInterface({
+			input: this.#engine.stdout,
+			crlfDelay: Infinity
+		});
+		this.#reader.on("line", this.#push.bind(this));
+		this.#reader.once("close", this.#finish.bind(this));
+	}
+	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	get pid() {
+		return this.#engine.pid;
+	}
+	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	get code() {
+		return this.#engine.code;
+	}
+	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	get signal() {
+		return this.#engine.signal;
+	}
+	/** The typed lifecycle observation surface. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
+	get lines() {
+		return this.#lines;
+	}
+	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	get evidence() {
+		return this.#engine.evidence;
+	}
+	/** True when the `lines` stream omitted output after a retention bound was reached. */
+	get truncated() {
+		return this.#truncated;
+	}
+	/** True after the terminal moment arrived and `exit` settled. */
+	get settled() {
+		return this.#engine.settled;
+	}
+	/** True after termination began, including after the terminal moment. */
+	get stopping() {
+		return this.#engine.stopping;
+	}
+	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	get exit() {
+		return this.#engine.exit;
+	}
+	/**
+	* Write 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
+	* prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
+	* full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
+	* terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
+	* 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
+	* the write can settle `true` without a callback error or a stream error while the child remains
+	* alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
+	* that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
+	* for bytes the package is about to discard.
+	*
+	* @param text - The line text without its trailing newline
+	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	*/
+	send(text) {
+		return this.#engine.deliver(Buffer.from(`${text}\n`, "utf8"));
+	}
+	/**
+	* 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 when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	*/
+	stop() {
+		return this.#engine.stop();
+	}
+	/**
+	* 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() {
+		return this.#engine.destroy();
+	}
+	#iterate() {
+		this.#requested = true;
+		return Object.freeze({ next: this.#next.bind(this) });
+	}
+	#next() {
+		const line = this.#take();
+		if (line !== void 0) return Promise.resolve(Object.freeze({
+			done: false,
+			value: line
+		}));
+		if (this.#ended) return Promise.resolve(Object.freeze({
+			done: true,
+			value: void 0
+		}));
+		const waiter = Promise.withResolvers();
+		this.#waiters.push(waiter);
+		return waiter.promise;
+	}
+	#take() {
+		if (this.#head >= this.#queue.length) return void 0;
+		const line = this.#queue[this.#head];
+		this.#queue[this.#head] = "";
+		this.#head += 1;
+		if (this.#head >= this.#queue.length) {
+			this.#queue.length = 0;
+			this.#head = 0;
+		}
+		if (line === void 0) return void 0;
+		this.#pending -= Buffer.byteLength(line) + 1;
+		this.#relieve();
+		return line;
+	}
+	#push(line) {
+		if (this.#ended) return;
+		const waiter = this.#waiters.shift();
+		if (waiter !== void 0) {
+			waiter.resolve(Object.freeze({
+				done: false,
+				value: line
+			}));
+			return;
+		}
+		const bytes = Buffer.byteLength(line) + 1;
+		const stopping = this.#engine.stopping;
+		const limit = stopping ? this.#backlog * 2 : this.#backlog;
+		if ((!this.#requested || stopping) && this.#pending + bytes > limit) {
+			this.#truncated = true;
+			return;
+		}
+		this.#queue.push(line);
+		this.#pending += bytes;
+		this.#restrain();
+	}
+	#restrain() {
+		if (this.#paused || this.#engine.stopping || !this.#requested) return;
+		if (this.#pending < this.#backlog) return;
+		this.#paused = true;
+		this.#reader.pause();
+	}
+	#relieve() {
+		if (!this.#paused || this.#ended) return;
+		if (!this.#engine.stopping && this.#pending > this.#backlog / 2) return;
+		this.#paused = false;
+		this.#reader.resume();
+	}
+	#finish() {
+		if (this.#ended) return;
+		this.#ended = true;
+		this.#paused = false;
+		for (const waiter of this.#waiters) waiter.resolve(Object.freeze({
+			done: true,
+			value: void 0
+		}));
+		this.#waiters.length = 0;
+	}
+	#reportStderr(chunk) {
+		this.#emitter.emit("stderr", chunk);
+	}
+	#reportFault(cause) {
+		this.#emitter.emit("error", cause);
+	}
+	#reportExit(exit) {
+		this.#emitter.emit("exit", exit);
+	}
+	#closeReader() {
+		this.#reader.close();
+	}
+	#releaseBackpressure() {
+		this.#capBacklog();
+		this.#relieve();
+	}
+	#capBacklog() {
+		const limit = this.#backlog * 2;
+		while (this.#pending > limit && this.#queue.length > this.#head) {
+			const line = this.#queue.pop();
+			if (line === void 0) break;
+			this.#pending -= Buffer.byteLength(line) + 1;
+			this.#truncated = true;
+		}
+	}
+};
+//#endregion
+//#region src/server/ProcessManager.ts
+/**
+* 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
+* itself and emits `exit`, so `count` and `processes` reflect only live children. The id is reserved
+* before the child is constructed and released when construction throws, so a refused launch never
+* strands its key. Eviction follows the child's own `exit` promise, which no listener can forge, so
+* it lands one microtask after the child's public `exit` event: a listener on that event still sees
+* the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
+* and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
+* getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
+* `exit`, never from `launch`. `destroy` awaits every child's own teardown, including the teardown
+* of a child a lost race refused, which destroys each child's observation emitter and leaves every
+* subscription on it silently inert, then destroys the registry emitter last.
+*
+* @example
+* ```ts
+* import { ProcessManager } from '@orkestrel/process/server'
+*
+* const manager = new ProcessManager()
+* const child = manager.launch('build', {
+* 	command: { file: 'node', arguments: ['build.js'] },
+* 	workspace: process.cwd(),
+* })
+* await child.exit
+* await manager.destroy()
+* ```
+*/
+var ProcessManager = class {
+	#emitter;
+	#children = /* @__PURE__ */ new Map();
+	#ids = /* @__PURE__ */ new Set();
+	#orphans = /* @__PURE__ */ new Set();
+	#destroying = false;
+	#ending;
+	/**
+	* Construct a process registry.
+	*
+	* @param options - Initial fleet-level observation hooks and listener-error handling
+	*/
 	constructor(options) {
 		const on = options?.on;
 		const error = options?.error;
@@ -1285,6 +1518,185 @@ var ProcessManager = class {
 	}
 };
 //#endregion
+//#region src/server/Session.ts
+/**
+* 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
+* import { Session } from '@orkestrel/process/server'
+*
+* const session = new Session({
+* 	command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+* 	workspace: process.cwd(),
+* })
+* ```
+*/
+var Session = class {
+	#emitter;
+	#engine;
+	#output;
+	/**
+	* Spawn one child process and begin 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) {
+		const command = options.command;
+		const workspace = options.workspace;
+		const grace = options.grace;
+		const drain = options.drain;
+		const evidence = options.evidence;
+		const delivery = options.delivery;
+		const signal = options.signal;
+		const on = options.on;
+		const error = options.error;
+		this.#emitter = new Emitter({
+			...on === void 0 ? {} : { on },
+			...error === void 0 ? {} : { error }
+		});
+		this.#output = this.#publish.bind(this);
+		this.#engine = new Supervisor({
+			command,
+			workspace,
+			writable: true,
+			...grace === void 0 ? {} : { grace },
+			...drain === void 0 ? {} : { drain },
+			...evidence === void 0 ? {} : { evidence },
+			...delivery === void 0 ? {} : { delivery },
+			...signal === void 0 ? {} : { signal }
+		}, {
+			chunk: this.#reportStderr.bind(this),
+			fault: this.#reportFault.bind(this),
+			close: this.#closeOutput.bind(this),
+			terminal: this.#reportExit.bind(this),
+			teardown: this.#emitter.destroy.bind(this.#emitter)
+		});
+		this.#engine.stdout.on("data", this.#output);
+	}
+	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	get pid() {
+		return this.#engine.pid;
+	}
+	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	get code() {
+		return this.#engine.code;
+	}
+	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	get signal() {
+		return this.#engine.signal;
+	}
+	/** The typed lifecycle observation surface. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	get evidence() {
+		return this.#engine.evidence;
+	}
+	/** True after the terminal moment arrived and `exit` settled. */
+	get settled() {
+		return this.#engine.settled;
+	}
+	/** True after termination began, including after the terminal moment. `end` never turns it true. */
+	get stopping() {
+		return this.#engine.stopping;
+	}
+	/** The child's own ending, awaited without the terminal moment's drain window. */
+	get ending() {
+		return this.#engine.ending;
+	}
+	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	get exit() {
+		return this.#engine.exit;
+	}
+	/**
+	* Writes raw bytes to the open standard-input channel.
+	*
+	* @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) {
+		return this.#engine.deliver(bytes);
+	}
+	/**
+	* 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
+	*/
+	end() {
+		return this.#engine.end();
+	}
+	/**
+	* 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() {
+		return this.#engine.stop();
+	}
+	/**
+	* 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() {
+		return this.#engine.destroy();
+	}
+	#publish(chunk) {
+		if (!Buffer.isBuffer(chunk) || this.#engine.settled) return;
+		this.#emitter.emit("stdout", new Uint8Array(chunk));
+	}
+	#reportStderr(chunk) {
+		this.#emitter.emit("stderr", chunk);
+	}
+	#reportFault(cause) {
+		this.#emitter.emit("error", cause);
+	}
+	#reportExit(exit) {
+		this.#emitter.emit("exit", exit);
+	}
+	#closeOutput() {
+		this.#engine.stdout.off("data", this.#output);
+	}
+};
+//#endregion
 //#region src/server/factories.ts
 /**
 * Creates one supervised child process.
@@ -1307,6 +1719,26 @@ function createProcess(options) {
 	return new Process(options);
 }
 /**
+* 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,
+* })
+* ```
+*/
+function createSession(options) {
+	return new Session(options);
+}
+/**
 * Creates one keyed registry of supervised child processes.
 *
 * @param options - Initial fleet-level observation hooks and listener-error handling
@@ -1660,6 +2092,6 @@ function detach(command, options) {
 	child.unref();
 }
 //#endregion
-export { Process, ProcessManager, Retention, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, createProcess, createProcessManager, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
+export { Process, ProcessManager, Retention, Session, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
 
 //# sourceMappingURL=index.js.map