@orkestrel/process 0.0.2 → 0.0.3

package/dist/src/server/index.cjs

@@ -1,40 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let node_buffer = require("node:buffer");
 let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
 let node_path = require("node:path");
+let _orkestrel_contract = require("@orkestrel/contract");
 let _src_core = require("../core/index.cjs");
 let node_readline = require("node:readline");
 let node_string_decoder = require("node:string_decoder");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/server/helpers.ts
 /**
-* Signals one owned child process, or its detached process group on a POSIX host.
-*
-* @remarks
-* On a POSIX host a child spawned `detached` leads its own process group, so signalling the
-* negated pid reaches the whole tree. On Windows, or when no pid is available, the signal goes to
-* the child directly. A throw during signalling is swallowed: the process can exit and win the
-* signal race, and the child's close event remains the authoritative terminal state.
-*
-* @param child - The child process signal boundary
-* @param signal - The signal to deliver
-* @returns Nothing
-*
-* @example
-* ```ts
-* killProcess(child, 'SIGTERM')
-* ```
-*/
-function killProcess(child, signal) {
-	try {
-		if (process.platform === "win32" || child.pid === void 0) {
-			child.kill(signal);
-			return;
-		}
-		process.kill(-child.pid, signal);
-	} catch {}
-}
-/**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
 *
 * @remarks
@@ -42,7 +17,7 @@ function killProcess(child, signal) {
 * multibyte sequence, the start advances past the leading continuation bytes so the retained
 * bytes always begin on a code-point boundary.
 *
-* @param buffer - The accumulated bytes
+* @param bytes - The accumulated bytes
 * @param limit - The maximum retained byte count
 * @returns The trailing bytes, at most `limit` and never starting mid-sequence
 *
@@ -51,7 +26,8 @@ function killProcess(child, signal) {
 * trimTail(Buffer.from('hello'), 3) // <Buffer 6c 6c 6f>
 * ```
 */
-function trimTail(buffer, limit) {
+function trimTail(bytes, limit) {
+	const buffer = node_buffer.Buffer.isBuffer(bytes) ? bytes : node_buffer.Buffer.from(bytes);
 	if (buffer.byteLength <= limit) return buffer;
 	let start = buffer.byteLength - limit;
 	while (start < buffer.byteLength) {
@@ -69,7 +45,7 @@ function trimTail(buffer, limit) {
 * 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.
 *
-* @param buffer - The accumulated bytes
+* @param bytes - The accumulated bytes
 * @param limit - The maximum retained byte count
 * @returns The leading bytes, at most `limit` and never ending mid-sequence
 *
@@ -78,7 +54,8 @@ function trimTail(buffer, limit) {
 * trimHead(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
 * ```
 */
-function trimHead(buffer, limit) {
+function trimHead(bytes, limit) {
+	const buffer = node_buffer.Buffer.isBuffer(bytes) ? bytes : node_buffer.Buffer.from(bytes);
 	if (buffer.byteLength <= limit) return buffer;
 	let end = limit;
 	while (end > 0) {
@@ -89,115 +66,555 @@ function trimHead(buffer, limit) {
 	return node_buffer.Buffer.from(buffer.subarray(0, end));
 }
 /**
-* Checks whether a command file must be spawned through a shell on the current host.
+* Renders one command into its diagnostic command line.
+*
+* @param command - The executable and its argument vector
+* @returns The space-joined command line, for a {@link RunResult} and error messages
+*
+* @example
+* ```ts
+* formatCommand({ file: 'git', arguments: ['status'] }) // 'git status'
+* ```
+*/
+function formatCommand(command) {
+	return [command.file, ...command.arguments].join(" ");
+}
+/**
+* Reads one environment variable the way the host resolves it.
+*
+* @remarks
+* Windows environment keys are case-insensitive, so a merged record can hold `Path` where the
+* caller asks for `PATH`. The exact key is tried first and a folded scan runs only on Windows.
+*
+* @param environment - The environment record to read
+* @param name - The variable name
+* @returns The value, or `undefined` when the environment declares no such variable
+*
+* @example
+* ```ts
+* readVariable({ Path: 'C:\\Windows' }, 'PATH') // 'C:\\Windows' on Windows
+* ```
+*/
+function readVariable(environment, name) {
+	const direct = environment[name];
+	if (direct !== void 0) return direct;
+	if (process.platform !== "win32") return void 0;
+	const target = name.toUpperCase();
+	for (const [key, value] of Object.entries(environment)) if (key.toUpperCase() === target) return value;
+}
+/**
+* Merges environment overrides into the environment one child receives.
+*
+* @remarks
+* Later maps override earlier ones and an `undefined` value unsets a key. On Windows the keys fold
+* case-insensitively and the last writer wins, so `PATH` followed by `Path` yields one variable
+* rather than two the host would resolve unpredictably.
+*
+* @param isolated - If `true`, the parent environment is excluded; if `false`, the overrides layer over it
+* @param base - The command's own environment overrides
+* @param override - Per-invocation overrides applied last
+* @returns The environment for a spawn, carrying no unset key
+*
+* @example
+* ```ts
+* mergeEnvironment(false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+* ```
+*/
+function mergeEnvironment(isolated, base, override) {
+	const folded = process.platform === "win32";
+	const layers = [
+		isolated ? {} : process.env,
+		base ?? {},
+		override ?? {}
+	];
+	const entries = /* @__PURE__ */ new Map();
+	for (const layer of layers) for (const [key, value] of Object.entries(layer)) {
+		const token = folded ? key.toUpperCase() : key;
+		if (value === void 0) {
+			entries.delete(token);
+			continue;
+		}
+		entries.set(token, [key, value]);
+	}
+	const merged = {};
+	for (const [key, value] of entries.values()) merged[key] = value;
+	return merged;
+}
+/**
+* Checks whether a path names a regular file.
+*
+* @remarks
+* Existence alone does not make a lookup hit: a directory named `git` on `PATH` is not the `git`
+* 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
+*
+* @example
+* ```ts
+* isFile(process.execPath) // true
+* ```
+*/
+function isFile(target) {
+	return (0, _orkestrel_contract.holds)(() => (0, node_fs.statSync)(target, { throwIfNoEntry: false })?.isFile() === true);
+}
+/**
+* Resolves a command file to the executable path the host would launch.
 *
 * @remarks
-* Node v22+ refuses to spawn a Windows `.cmd` or `.bat` batch file directly and returns `EINVAL`,
-* and a bare command name such as `git` resolves through `PATHEXT` to a batch shim rather than an
-* executable. Both cases run through the shell. A POSIX host, and a Windows path carrying a real
-* executable extension such as `.exe`, spawn directly. When the result is `true`, treat the
-* command file and arguments as trusted: shell invocation exposes shell metacharacters.
+* Windows alone needs this: the host searches the working directory before `PATH` and applies
+* `PATHEXT`, and Node reproduces neither for a direct spawn. Within each searched directory the
+* literal name is tried first and each `PATHEXT` candidate after it, whether or not the name already
+* carries an extension — so `report.txt` resolves to a `report.txt` file where one exists and to
+* `report.txt.cmd` where none does. The lookup reads the child's effective environment, so an
+* overridden `PATH` selects the executable the child would have found. A POSIX host resolves the
+* file itself, so the answer there is always `undefined`. An appended extension is spelled the way
+* `PATHEXT` spells it rather than the way the directory entry does, which the case-insensitive host
+* treats as the same file.
 *
 * @param file - The command executable name or path
-* @returns True when the file must run through a shell; false when it spawns directly
+* @param options - The directory searched first and the child's effective environment
+* @returns The resolved absolute path, or `undefined` when no candidate is a regular file
 *
 * @example
 * ```ts
-* requiresShell('git') // true on Windows, false on POSIX
+* resolveExecutable('git', {}) ?? 'git' // an absolute path on Windows, 'git' elsewhere
 * ```
 */
-function requiresShell(file) {
-	if (process.platform !== "win32") return false;
-	const lower = file.toLowerCase();
-	return lower.endsWith(".cmd") || lower.endsWith(".bat") || (0, node_path.extname)(file) === "";
+function resolveExecutable(file, options) {
+	if (process.platform !== "win32") return void 0;
+	const environment = options?.environment ?? process.env;
+	const workspace = options?.workspace ?? process.cwd();
+	const candidates = [file, ...(readVariable(environment, "PATHEXT") ?? _src_core.PROCESS_PATHEXT).split(";").filter((extension) => extension.length > 0).map((extension) => `${file}${extension}`)];
+	const directories = file.includes("/") || file.includes("\\") ? [workspace] : [workspace, ...(readVariable(environment, "PATH") ?? "").split(node_path.delimiter)];
+	for (const directory of directories) {
+		if (directory.length === 0) continue;
+		for (const candidate of candidates) {
+			const target = (0, node_path.resolve)(directory, candidate);
+			if (isFile(target)) return target;
+		}
+	}
 }
 /**
-* Renders one command into its diagnostic command line.
+* Quotes one command-line token for a `cmd.exe` command line.
+*
+* @remarks
+* A token carrying whitespace or a shell metacharacter is wrapped in double quotes so `cmd.exe`
+* passes it as one literal argument; an embedded double quote is doubled, which is how `cmd.exe`
+* reads a literal quote inside a quoted token. Every other token is left exactly as written, so a
+* batch script still receives `%1` without added quotes.
+*
+* @param value - The token to quote
+* @returns The token, quoted only when `cmd.exe` would otherwise split or interpret it
+*
+* @example
+* ```ts
+* quoteArgument('a&b') // '"a&b"'
+* ```
+*/
+function quoteArgument(value) {
+	if (value.length > 0 && !/[\s"&|<>^()%!]/.test(value)) return value;
+	return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+/**
+* Builds the resolved spawn form of one command.
+*
+* @remarks
+* The executable is resolved against the child's effective environment. A resolved `.cmd` or `.bat`
+* script cannot be spawned directly **on Windows**, so it runs there through an explicitly quoted
+* `cmd.exe /d /s /c` command line with the argument vector passed verbatim. No path uses a shell,
+* so a metacharacter in an argument is never interpreted. `cmd.exe` expands `%NAME%` before it
+* parses quotes, so no quoting can carry a percent sign through to a Windows batch target: an
+* argument carrying one is refused there rather than silently rewritten. The whole batch path is
+* Windows-only. A POSIX host has no `cmd.exe` and no restriction on spawning a file directly, so a
+* target named `worker.cmd` spawns directly there and receives a percent sign as literal text.
 *
 * @param command - The executable and its argument vector
-* @returns The space-joined command line, for a {@link RunResult} and error messages
+* @param options - The directory searched first and the child's effective environment
+* @returns The file, argument vector, and verbatim flag to spawn with
+* @throws A {@link ProcessError} coded `invalid` when the host is Windows, the resolved target is a batch script, and an argument carries a percent sign
 *
 * @example
 * ```ts
-* commandLine({ file: 'git', arguments: ['status'] }) // 'git status'
+* buildSpawn({ file: 'node', arguments: ['--version'] }).verbatim // false
 * ```
 */
-function commandLine(command) {
-	return [command.file, ...command.arguments].join(" ");
+function buildSpawn(command, options) {
+	const file = resolveExecutable(command.file, options) ?? command.file;
+	const extension = (0, node_path.extname)(file).toLowerCase();
+	if (!(process.platform === "win32" && (extension === ".cmd" || extension === ".bat"))) return Object.freeze({
+		file,
+		arguments: Object.freeze([...command.arguments]),
+		verbatim: false
+	});
+	for (const argument of command.arguments) if (argument.includes("%")) throw (0, _src_core.createInvalidError)("command argument", argument);
+	const line = [`"${file}"`, ...command.arguments.map(quoteArgument)].join(" ");
+	const environment = options?.environment ?? process.env;
+	return Object.freeze({
+		file: readVariable(environment, "ComSpec") ?? "cmd.exe",
+		arguments: Object.freeze([
+			"/d",
+			"/s",
+			"/c",
+			`"${line}"`
+		]),
+		verbatim: true
+	});
 }
 /**
-* Merges environment overrides over the current process environment.
+* Validates one spawn-bound string.
 *
 * @remarks
-* Later maps override earlier ones and an `undefined` value unsets a key. The base is the parent
-* process environment, so a child inherits it unless a key is overridden or unset.
+* A NUL character terminates a string for the host, so it is refused everywhere rather than
+* reaching the spawn as a raw `ERR_INVALID_ARG_VALUE`.
 *
-* @param base - The command's own environment overrides
-* @param override - Per-invocation overrides applied last
-* @returns The merged environment for a spawn
+* @param value - The value to inspect
+* @param subject - The rejected input named as the caller wrote it, such as `command file`
+* @param required - If `true`, an empty string is refused; if `false`, it is accepted
+* @returns Nothing; a successful return means the string is spawn-safe
+* @throws A {@link ProcessError} coded `invalid` when the value is not a string, carries a NUL, or is required and empty
+*
+* @example
+* ```ts
+* validateText('status', 'command argument', false) // returns
+* ```
+*/
+function validateText(value, subject, required) {
+	if (!(0, _orkestrel_contract.isString)(value) || value.includes("\0")) throw (0, _src_core.createInvalidError)(subject, value);
+	if (required && !(0, _orkestrel_contract.isNonEmptyString)(value)) throw (0, _src_core.createInvalidError)(subject, value);
+}
+/**
+* Validates one timer-valued option in milliseconds.
+*
+* @remarks
+* The host truncates a fractional delay and converts anything above {@link PROCESS_TIMER} to one
+* millisecond, so a requested 25-day timeout would otherwise fire immediately.
+*
+* @param value - The value to inspect, or `undefined` when the option was omitted
+* @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
+* @returns Nothing; a successful return means the value schedules as written
+* @throws A {@link ProcessError} coded `invalid` when the value is not a non-negative integer at or below `PROCESS_TIMER`
+*
+* @example
+* ```ts
+* validateTimer(5_000, "option 'grace'") // returns
+* ```
+*/
+function validateTimer(value, subject) {
+	if (value === void 0) return;
+	if (!(0, _orkestrel_contract.isNonNegativeInteger)(value) || !(0, _orkestrel_contract.boundsOf)(0, _src_core.PROCESS_TIMER)(value)) throw (0, _src_core.createInvalidError)(subject, value);
+}
+/**
+* Validates one byte-valued option.
+*
+* @param value - The value to inspect, or `undefined` when the option was omitted
+* @param subject - The rejected input named as the caller wrote it, such as `option 'limit'`
+* @param minimum - The smallest accepted value
+* @returns Nothing; a successful return means the value bounds a real byte count
+* @throws A {@link ProcessError} coded `invalid` when the value is not a safe integer at or above `minimum`
+*
+* @example
+* ```ts
+* validateBytes(1_024, "option 'limit'", 0) // returns
+* ```
+*/
+function validateBytes(value, subject, minimum) {
+	if (value === void 0) return;
+	if (!(0, _orkestrel_contract.isNonNegativeInteger)(value) || !(0, _orkestrel_contract.boundsOf)(minimum, Number.MAX_SAFE_INTEGER)(value)) throw (0, _src_core.createInvalidError)(subject, value);
+}
+/**
+* Validates every spawn-bound string of one environment override map.
+*
+* @remarks
+* The host refuses a NUL in a variable name or value with a raw `ERR_INVALID_ARG_VALUE`, so the same
+* refusal runs here for a command's own overrides and for a per-invocation override map alike.
+*
+* @param environment - The override map, or `undefined` when none was supplied
+* @returns Nothing; a successful return means every name and value reaches the host intact
+* @throws A {@link ProcessError} coded `invalid` when a name is empty or a name or value carries a NUL
+*
+* @example
+* ```ts
+* validateEnvironment({ TOKEN: 'a' }) // returns
+* ```
+*/
+function validateEnvironment(environment) {
+	if (environment === void 0) return;
+	for (const [key, value] of Object.entries(environment)) {
+		validateText(key, "environment key", true);
+		if (value !== void 0) validateText(value, "environment value", false);
+	}
+}
+/**
+* Validates every spawn-bound string of one command.
+*
+* @param command - The executable, arguments, and optional environment overrides
+* @returns Nothing; a successful return means the command reaches the host intact
+* @throws A {@link ProcessError} coded `invalid` when the file is empty or any string carries a NUL
+*
+* @example
+* ```ts
+* validateCommand({ file: 'git', arguments: ['status'] }) // returns
+* ```
+*/
+function validateCommand(command) {
+	validateText(command.file, "command file", true);
+	for (const argument of command.arguments) validateText(argument, "command argument", false);
+	validateEnvironment(command.environment);
+}
+/**
+* Validates the working directory one child starts in.
+*
+* @param workspace - The directory, or `undefined` when the option was omitted
+* @returns Nothing; a successful return means the directory reaches the host intact
+* @throws A {@link ProcessError} coded `invalid` when the directory is empty or carries a NUL
+*
+* @example
+* ```ts
+* validateWorkspace(process.cwd()) // returns
+* ```
+*/
+function validateWorkspace(workspace) {
+	if (workspace === void 0) return;
+	validateText(workspace, "workspace", true);
+}
+/**
+* Retains one delivered chunk up to a byte limit and records what the stream delivered.
+*
+* @remarks
+* The retained head is kept as chunk slices and joined once, so a long stream never repeatedly
+* concatenates a growing buffer. `counts` is a two-slot tally: slot `0` counts every delivered byte
+* and slot `1` counts the retained bytes, so a caller compares slot `0` against `limit` to learn
+* whether the capture was truncated.
+*
+* @param chunk - The delivered chunk, ignored when it is not a buffer
+* @param chunks - The retained head, appended to in place
+* @param counts - The `[delivered, retained]` tally, updated in place
+* @param limit - The maximum retained byte count
+* @returns Nothing
+*
+* @example
+* ```ts
+* const chunks: Buffer[] = []
+* const counts = [0, 0]
+* retainChunk(Buffer.from('hello'), chunks, counts, 3)
+* counts[1] // 3
+* ```
+*/
+function retainChunk(chunk, chunks, counts, limit) {
+	if (!node_buffer.Buffer.isBuffer(chunk)) return;
+	const delivered = counts[0] ?? 0;
+	const retained = counts[1] ?? 0;
+	counts[0] = delivered + chunk.byteLength;
+	const room = limit - retained;
+	if (room <= 0) return;
+	const slice = chunk.byteLength <= room ? chunk : node_buffer.Buffer.from(chunk.subarray(0, room));
+	chunks.push(slice);
+	counts[1] = retained + slice.byteLength;
+}
+/**
+* Checks whether a child process has reached its native exit.
+*
+* @remarks
+* The host sets exactly one of these fields when the process ends, so together they are the
+* authoritative liveness answer. Reading them before each signal is what keeps a signal from being
+* 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
+*
+* @example
+* ```ts
+* isExited({ exitCode: 0, signalCode: null }) // true
+* ```
+*/
+function isExited(child) {
+	return child.exitCode !== null || child.signalCode !== null;
+}
+/**
+* Signals one owned child process, or its detached process group on a POSIX host.
+*
+* @remarks
+* On a POSIX host a child spawned `detached` leads its own process group, so signalling the
+* negated pid reaches the whole tree. On Windows, or when no pid is available, the signal goes to
+* the child directly. A throw during signalling is swallowed: the process can exit between the
+* caller's liveness check and this call, and the child's native exit remains the authoritative
+* terminal state.
+*
+* @param child - The child boundary
+* @param signal - The signal to deliver
+* @returns Nothing
 *
 * @example
 * ```ts
-* mergeEnvironment({ TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+* killProcess(child, 'SIGTERM')
 * ```
 */
-function mergeEnvironment(base, override) {
-	return {
-		...process.env,
-		...base,
-		...override
-	};
+function killProcess(child, signal) {
+	try {
+		if (process.platform === "win32" || child.pid === void 0) {
+			child.kill(signal);
+			return;
+		}
+		process.kill(-child.pid, signal);
+	} catch {}
 }
 /**
-* Builds one settled {@link RunResult} from a completed one-shot run's captured bytes and exit.
+* Kills one Windows process tree through `taskkill`.
 *
 * @remarks
-* `failed` is derived: a run failed when it timed out, was ended by a signal, or exited with a
-* code other than `0` — a `null` code from a spawn fault is therefore a failure. Both output
-* buffers are byte-bounded by `limit` before decoding.
-*
-* @param command - The diagnostic command line
-* @param stdout - The captured standard output bytes
-* @param stderr - The captured standard error bytes
-* @param code - The exit code, or `null` when a signal or spawn fault ended the run
-* @param signal - The terminating signal, or `null`
-* @param timedOut - If `true`, the run's own timeout elapsed; if `false`, it did not
-* @param limit - The maximum captured bytes for each stream
+* Windows has no process group a signal can reach, so the whole tree is ended by the host utility,
+* addressed by its absolute `System32` path so a `PATH` override cannot substitute another program.
+* The call is bounded: it is killed itself when `timeout` elapses, which is what keeps a termination
+* from waiting on the host indefinitely. A tree is discoverable only while its root lives, so a
+* descendant that outlives the root is beyond this mechanism.
+*
+* @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
+*
+* @example
+* ```ts
+* await killTree(child.pid ?? 0, 5_000)
+* ```
+*/
+function killTree(pid, timeout) {
+	const settled = Promise.withResolvers();
+	const executable = (0, node_path.join)(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe");
+	const killer = (0, node_child_process.spawn)(executable, [
+		"/F",
+		"/T",
+		"/PID",
+		String(pid)
+	], {
+		stdio: "ignore",
+		windowsHide: true,
+		timeout
+	});
+	killer.once("error", () => settled.resolve(false));
+	killer.once("close", (code) => settled.resolve(code === 0));
+	return settled.promise;
+}
+/**
+* Waits for one child process's native exit, bounded by a deadline.
+*
+* @param child - The child boundary
+* @param timeout - The milliseconds to wait before giving up
+* @returns A promise that resolves on the native exit or when the deadline elapses, whichever comes first
+*
+* @example
+* ```ts
+* await waitForExit(child, 5_000)
+* ```
+*/
+function waitForExit(child, timeout) {
+	if (isExited(child)) return Promise.resolve();
+	const settled = Promise.withResolvers();
+	const timer = setTimeout(settled.resolve, timeout);
+	child.once("exit", () => {
+		clearTimeout(timer);
+		settled.resolve();
+	});
+	return settled.promise;
+}
+/**
+* Terminates one child process tree and reports whether its native exit was observed.
+*
+* @remarks
+* Windows ends the tree at once through {@link killTree}, falling back to a direct kill when the
+* utility fails, because the host has no cooperative termination to offer. A POSIX host signals the
+* process group `SIGTERM`, waits `grace`, then signals `SIGKILL`. No signal is initiated once the
+* native exit is observed; the window between initiating a signal and the host delivering it belongs
+* to the operating system. `confirm` bounds each awaited step rather than the call as a whole: on
+* Windows it bounds the `taskkill` call and then the final wait, and on a POSIX host `grace` bounds
+* the cooperative wait and `confirm` the final one. Never rejects.
+*
+* @param child - The child boundary
+* @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
+* @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
+*
+* @example
+* ```ts
+* const confirmed = await stopChild(child, 5_000, 5_000)
+* ```
+*/
+async function stopChild(child, grace, confirm) {
+	if (isExited(child)) return true;
+	if (process.platform === "win32") {
+		if (!(child.pid === void 0 ? false : await killTree(child.pid, confirm)) && !isExited(child)) killProcess(child, "SIGKILL");
+	} else {
+		killProcess(child, "SIGTERM");
+		await waitForExit(child, grace);
+		if (!isExited(child)) killProcess(child, "SIGKILL");
+	}
+	if (isExited(child)) return true;
+	await waitForExit(child, confirm);
+	return isExited(child);
+}
+/**
+* Builds one settled {@link RunResult} from a completed run's captured bytes and terminal facts.
+*
+* @remarks
+* `failed` is derived: a run failed when it timed out, was aborted, ended on a host fault, was ended
+* by a signal, or exited with a code other than `0` — a `null` code from a spawn fault is therefore
+* a failure. Both byte fields are bounded by `limit` on a code-point boundary here, which is the one
+* place the captured bytes are decoded.
+*
+* @param input - The captured bytes, terminal state, and capture limit
 * @returns The frozen run outcome
 *
 * @example
 * ```ts
-* buildRunResult('git status', Buffer.from('ok'), Buffer.alloc(0), 0, null, false, 1024)
+* buildRunResult({
+* 	command: 'git status',
+* 	stdout: Buffer.from('ok'),
+* 	stderr: Buffer.alloc(0),
+* 	code: 0,
+* 	signal: null,
+* 	expired: false,
+* 	aborted: false,
+* 	truncated: false,
+* 	limit: 1_024,
+* }).failed // false
 * ```
 */
-function buildRunResult(command, stdout, stderr, code, signal, timedOut, limit) {
+function buildRunResult(input) {
 	return Object.freeze({
-		command,
-		stdout: trimHead(stdout, limit).toString("utf8"),
-		stderr: trimHead(stderr, limit).toString("utf8"),
-		code,
-		signal,
-		failed: timedOut || signal !== null || code !== 0,
-		timedOut
+		command: input.command,
+		stdout: trimHead(input.stdout, input.limit).toString("utf8"),
+		stderr: trimHead(input.stderr, input.limit).toString("utf8"),
+		code: input.code,
+		signal: input.signal,
+		failed: input.expired || input.aborted || input.cause !== void 0 || input.signal !== null || input.code !== 0,
+		expired: input.expired,
+		aborted: input.aborted,
+		truncated: input.truncated
 	});
 }
 /**
 * Runs one command to completion, buffering its output, and settles with the outcome.
 *
 * @remarks
-* The child is spawned through the cross-platform command resolver ({@link requiresShell}) and, on
-* a POSIX host, detached so its whole process group can be terminated. Standard output and error
-* are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` arms a
-* timer that terminates the child through `SIGTERM`, then `SIGKILL` after `grace`
-* (default {@link PROCESS_GRACE}); aborting `signal` terminates the same way. The child's
-* `environment` merges over the parent, then `options.environment` on top, and `options.input`
-* overrides `command.input`. Unless `reject` is `false`, a failed run rejects with a
-* {@link createRunError} carrying the {@link RunResult}.
+* 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
+* child through the same bounded stop, and only the first of them 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
+* covers a terminated run alone: a run with no `timeout` and no `signal` settles on stdio completion
+* rather than on process exit, so a descendant that inherited the child's stdio holds the run open
+* after the child itself has gone. Give such a run a `timeout`. The child's `environment` merges over
+* the parent unless the command is `isolated`, then `options.environment` on top, and `options.input`
+* overrides `command.input`. Unless `strict` is `false`, a failed run rejects with a
+* {@link createRunError} carrying the {@link RunResult}. An invalid option or command string rejects
+* before the child is spawned, because an async function cannot throw synchronously.
 *
 * @param command - The executable, arguments, and optional environment and input
-* @param options - Working directory, timeout, grace, signal, capture limit, and reject behavior
+* @param options - Working directory, timeout, grace, signal, capture limit, and failure delivery
 * @returns The settled run outcome
-* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+* @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link RunResult} when the run failed and `strict` is not `false`
 *
 * @example
 * ```ts
@@ -205,140 +622,238 @@ function buildRunResult(command, stdout, stderr, code, signal, timedOut, limit)
 * ```
 */
 async function run(command, options) {
+	validateCommand(command);
+	validateEnvironment(options?.environment);
+	validateWorkspace(options?.workspace);
+	validateTimer(options?.timeout, "option 'timeout'");
+	validateTimer(options?.grace, "option 'grace'");
+	validateBytes(options?.limit, "option 'limit'", 0);
 	const limit = options?.limit ?? _src_core.PROCESS_OUTPUT;
 	const grace = options?.grace ?? _src_core.PROCESS_GRACE;
 	const timeout = options?.timeout ?? 0;
-	const reject = options?.reject ?? true;
-	const input = options?.input ?? command.input;
-	const line = commandLine(command);
+	const strict = options?.strict ?? true;
+	const text = options?.input ?? command.input;
+	const line = formatCommand(command);
+	const workspace = options?.workspace ?? process.cwd();
+	const environment = mergeEnvironment(command.isolated === true, command.environment, options?.environment);
+	const plan = buildSpawn(command, {
+		workspace,
+		environment
+	});
 	const settled = Promise.withResolvers();
 	const terminate = new AbortController();
 	const cleanup = new AbortController();
-	let stdout = node_buffer.Buffer.alloc(0);
-	let stderr = node_buffer.Buffer.alloc(0);
-	let timedOut = false;
-	let launchCause;
-	let killTimer;
+	const finish = new AbortController();
+	const outChunks = [];
+	const errChunks = [];
+	const outCounts = [0, 0];
+	const errCounts = [0, 0];
+	let spawned = false;
+	let expired = false;
+	let aborted = false;
+	let cause;
 	let timeoutTimer;
-	let done = false;
-	const child = (0, node_child_process.spawn)(command.file, [...command.arguments], {
-		cwd: options?.workspace ?? process.cwd(),
+	let confirmTimer;
+	const child = (0, node_child_process.spawn)(plan.file, [...plan.arguments], {
+		cwd: workspace,
 		detached: process.platform !== "win32",
-		env: mergeEnvironment(command.environment, options?.environment),
+		env: environment,
 		stdio: [
 			"pipe",
 			"pipe",
 			"pipe"
 		],
-		shell: requiresShell(command.file),
-		windowsHide: true
+		windowsHide: true,
+		windowsVerbatimArguments: plan.verbatim
 	});
+	finish.signal.addEventListener("abort", () => {
+		clearTimeout(timeoutTimer);
+		clearTimeout(confirmTimer);
+		cleanup.abort();
+		settled.resolve(buildRunResult({
+			command: line,
+			stdout: node_buffer.Buffer.concat(outChunks),
+			stderr: node_buffer.Buffer.concat(errChunks),
+			code: child.exitCode,
+			signal: child.signalCode,
+			expired,
+			aborted,
+			truncated: (outCounts[0] ?? 0) > limit || (errCounts[0] ?? 0) > limit,
+			limit,
+			...cause === void 0 ? {} : { cause }
+		}));
+	}, { once: true });
 	terminate.signal.addEventListener("abort", () => {
-		killProcess(child, "SIGTERM");
-		killTimer = setTimeout(() => killProcess(child, "SIGKILL"), grace);
+		clearTimeout(timeoutTimer);
+		cleanup.abort();
+		stopChild(child, grace, _src_core.PROCESS_CONFIRMATION).then(() => {
+			if (finish.signal.aborted) return;
+			confirmTimer = setTimeout(() => finish.abort(), _src_core.PROCESS_CONFIRMATION);
+		});
 	}, { once: true });
 	child.stdin.on("error", () => void 0);
-	child.stdout.on("data", (chunk) => {
-		if (node_buffer.Buffer.isBuffer(chunk)) stdout = trimHead(node_buffer.Buffer.concat([stdout, chunk]), limit);
+	child.stdout.on("data", (chunk) => retainChunk(chunk, outChunks, outCounts, limit));
+	child.stderr.on("data", (chunk) => retainChunk(chunk, errChunks, errCounts, limit));
+	child.once("spawn", () => {
+		spawned = true;
 	});
-	child.stderr.on("data", (chunk) => {
-		if (node_buffer.Buffer.isBuffer(chunk)) stderr = trimHead(node_buffer.Buffer.concat([stderr, chunk]), limit);
+	child.once("error", (error) => {
+		if (spawned) return;
+		cause = error;
+		finish.abort();
 	});
-	child.once("error", (cause) => {
-		if (done) return;
-		done = true;
-		launchCause = cause;
-		cleanup.abort();
-		clearTimeout(killTimer);
-		clearTimeout(timeoutTimer);
-		settled.resolve(buildRunResult(line, stdout, stderr, null, null, false, limit));
-	});
-	child.once("close", (code, signal) => {
-		if (done) return;
-		done = true;
-		cleanup.abort();
-		clearTimeout(killTimer);
-		clearTimeout(timeoutTimer);
-		settled.resolve(buildRunResult(line, stdout, stderr, code, signal, timedOut, limit));
-	});
-	if (input !== void 0) child.stdin.write(input);
+	child.once("close", () => finish.abort());
+	if (text !== void 0) child.stdin.write(text);
 	child.stdin.end();
 	if (timeout > 0) timeoutTimer = setTimeout(() => {
-		timedOut = true;
+		expired = true;
 		terminate.abort();
 	}, timeout);
 	if (options?.signal !== void 0) {
 		const signal = options.signal;
-		signal.addEventListener("abort", () => terminate.abort(), {
+		signal.addEventListener("abort", () => {
+			aborted = true;
+			terminate.abort();
+		}, {
 			once: true,
 			signal: cleanup.signal
 		});
-		if (signal.aborted) terminate.abort();
+		if (signal.aborted) {
+			aborted = true;
+			terminate.abort();
+		}
 	}
 	const result = await settled.promise;
-	if (result.failed && reject) throw (0, _src_core.createRunError)(result, launchCause);
+	if (result.failed && strict) throw (0, _src_core.createRunError)(result, cause);
 	return result;
 }
 /**
 * Runs one command to completion synchronously, buffering its output, and returns the outcome.
 *
 * @remarks
-* The synchronous counterpart of {@link run}. The child is spawned through the same cross-platform
-* command resolver ({@link requiresShell}). Standard output and error are each byte-bounded by
-* `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` is enforced by the host, which
-* ends the child with `SIGKILL` when it elapses. The environment and input follow the same merge
-* as {@link run}. Unless `reject` is `false`, a failed run throws a {@link createRunError} carrying
-* the {@link RunResult}.
+* The synchronous counterpart of {@link run}, spawned through the same resolver and never through a
+* shell. The host offers no cooperative termination window and no in-flight cancellation, so this
+* contract carries neither. A positive `timeout` and an output overflow both end the child with
+* `SIGKILL`: an overflow reports `truncated` and `failed` together and trims the partial output to
+* `limit`, where {@link run} keeps reading and reports `truncated` without failing. The environment
+* and input follow the same merge as {@link run}. Unless `strict` is `false`, a failed run throws a
+* {@link createRunError} carrying the {@link RunResult}.
 *
 * @param command - The executable, arguments, and optional environment and input
-* @param options - Working directory, timeout, signal, capture limit, and reject behavior
+* @param options - Working directory, timeout, capture limit, and failure delivery
 * @returns The run outcome
-* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+* @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link RunResult} when the run failed and `strict` is not `false`
 *
 * @example
 * ```ts
-* const result = runSync({ file: 'git', arguments: ['--version'] }, { reject: false })
+* const result = runSync({ file: 'git', arguments: ['--version'] }, { strict: false })
 * ```
 */
 function runSync(command, options) {
+	validateCommand(command);
+	validateEnvironment(options?.environment);
+	validateWorkspace(options?.workspace);
+	validateTimer(options?.timeout, "option 'timeout'");
+	validateBytes(options?.limit, "option 'limit'", 0);
 	const limit = options?.limit ?? _src_core.PROCESS_OUTPUT;
 	const timeout = options?.timeout ?? 0;
-	const reject = options?.reject ?? true;
-	const input = options?.input ?? command.input;
-	const line = commandLine(command);
-	const outcome = (0, node_child_process.spawnSync)(command.file, [...command.arguments], {
-		cwd: options?.workspace ?? process.cwd(),
-		env: mergeEnvironment(command.environment, options?.environment),
+	const strict = options?.strict ?? true;
+	const text = options?.input ?? command.input;
+	const line = formatCommand(command);
+	const workspace = options?.workspace ?? process.cwd();
+	const environment = mergeEnvironment(command.isolated === true, command.environment, options?.environment);
+	const plan = buildSpawn(command, {
+		workspace,
+		environment
+	});
+	const outcome = (0, node_child_process.spawnSync)(plan.file, [...plan.arguments], {
+		cwd: workspace,
+		env: environment,
 		encoding: "buffer",
 		maxBuffer: limit,
-		shell: requiresShell(command.file),
+		killSignal: "SIGKILL",
 		windowsHide: true,
-		...input !== void 0 ? { input } : {},
-		...options?.signal !== void 0 ? { signal: options.signal } : {},
-		...timeout > 0 ? {
-			timeout,
-			killSignal: "SIGKILL"
-		} : {}
+		windowsVerbatimArguments: plan.verbatim,
+		...text !== void 0 ? { input: text } : {},
+		...timeout > 0 ? { timeout } : {}
 	});
 	const error = outcome.error;
-	const timedOut = error !== void 0 && "code" in error && error.code === "ETIMEDOUT";
-	const result = buildRunResult(line, node_buffer.Buffer.isBuffer(outcome.stdout) ? outcome.stdout : node_buffer.Buffer.alloc(0), node_buffer.Buffer.isBuffer(outcome.stderr) ? outcome.stderr : node_buffer.Buffer.alloc(0), outcome.status, outcome.signal, timedOut, limit);
-	if (result.failed && reject) throw (0, _src_core.createRunError)(result, outcome.error);
+	const fault = error !== void 0 && "code" in error && (0, _orkestrel_contract.isString)(error.code) ? error.code : "";
+	const result = buildRunResult({
+		command: line,
+		stdout: node_buffer.Buffer.isBuffer(outcome.stdout) ? outcome.stdout : node_buffer.Buffer.alloc(0),
+		stderr: node_buffer.Buffer.isBuffer(outcome.stderr) ? outcome.stderr : node_buffer.Buffer.alloc(0),
+		code: outcome.status,
+		signal: outcome.signal,
+		expired: fault === "ETIMEDOUT",
+		aborted: false,
+		truncated: fault === "ENOBUFS",
+		limit,
+		...error === void 0 ? {} : { cause: error }
+	});
+	if (result.failed && strict) throw (0, _src_core.createRunError)(result, error);
 	return result;
 }
+/**
+* Spawns one command as a detached process and returns without waiting for it.
+*
+* @remarks
+* The child owns no stdio and is unreferenced, so it outlives this process and nothing here observes
+* its outcome. The error listener is attached before the child is unreferenced, so a post-spawn host
+* fault is swallowed rather than crashing the caller; an invalid command is refused before anything
+* is spawned.
+*
+* @param command - The executable, arguments, and optional environment
+* @param options - The working directory the detached child starts in
+* @returns Nothing
+* @throws A {@link ProcessError} coded `invalid` when the working directory or a command string is malformed
+*
+* @example
+* ```ts
+* detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
+* ```
+*/
+function detach(command, options) {
+	validateCommand(command);
+	validateWorkspace(options?.workspace);
+	const workspace = options?.workspace ?? process.cwd();
+	const environment = mergeEnvironment(command.isolated === true, command.environment);
+	const plan = buildSpawn(command, {
+		workspace,
+		environment
+	});
+	const child = (0, node_child_process.spawn)(plan.file, [...plan.arguments], {
+		cwd: workspace,
+		detached: true,
+		env: environment,
+		stdio: "ignore",
+		windowsHide: true,
+		windowsVerbatimArguments: plan.verbatim
+	});
+	child.once("error", () => void 0);
+	child.unref();
+}
 //#endregion
 //#region src/server/Process.ts
 /**
-* One supervised child process with eagerly framed output and bounded termination.
+* One supervised child process with framed output, a bounded backlog, and bounded termination.
 *
 * @remarks
-* Standard output is drained eagerly through `readline`, so `exit` resolves and a late consumer of
-* `lines` still receives every framed line, including a final line written without a trailing
-* newline. Standard error is decoded and forwarded live as the `stderr` event while a byte-bounded
+* Standard output is framed through `readline` into a single-consumer stream: each line goes to
+* exactly one waiting iterator, so two iterators split the output rather than each receiving all of
+* it. While no consumer has ever requested an iterator,
+* stdout keeps draining so `exit` still resolves, and retention stops at the `backlog` mark: a
+* consumer attaching later receives the retained head, a gap, then the live stream. Once an iterator
+* has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
+* nothing and the child feels real backpressure. The mark is soft — the host delivers whole chunks,
+* so the backlog overshoots it by up to one delivered chunk plus the drain that termination
+* releases. Standard error is decoded and forwarded live as the `stderr` event while a byte-bounded
 * raw tail is retained as `evidence`. The typed `emitter` also carries the child `error` cause on a
-* spawn fault and the terminal `exit`, alongside the `exit` promise. `stop` terminates the child
-* through `SIGTERM`, then `SIGKILL` after
-* `grace`, and is idempotent; `destroy` stops the child and destroys the emitter last.
+* spawn fault and the terminal `exit`, alongside the `exit` promise. `stop` ends the whole tree and
+* reports whether the native exit was observed; `destroy` stops the child, destroys stdin so every
+* pending `send` settles, and destroys the emitter last. `destroy` resolving does not imply the
+* child's stdio has closed, so `exit` and `lines` can still be outstanding when a descendant holds
+* an inherited pipe.
 *
 * @example
 * ```ts
@@ -347,7 +862,6 @@ function runSync(command, options) {
 * const child = new Process({
 * 	command: { file: 'node', arguments: ['--version'] },
 * 	workspace: process.cwd(),
-* 	grace: 5000,
 * })
 * const exit = await child.exit
 * await child.destroy()
@@ -358,45 +872,74 @@ var Process = class {
 	#child;
 	#reader;
 	#grace;
-	#limit;
+	#evidence;
+	#backlog;
 	#decoder = new node_string_decoder.StringDecoder("utf8");
 	#exit = Promise.withResolvers();
 	#lines;
-	#buffer = [];
+	#queue = [];
 	#waiters = [];
 	#signal;
 	#abort;
 	#tail = node_buffer.Buffer.alloc(0);
+	#head = 0;
+	#pending = 0;
+	#requested = false;
+	#paused = false;
+	#terminating = false;
 	#closed = false;
 	#ended = false;
 	#stopping;
 	#ending;
 	/**
-	* Spawn one child process and begin eager stream capture.
+	* Spawn one child process and begin stream capture.
 	*
-	* @param options - Command, workspace, termination, evidence, stdin, and observation settings
+	* @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 command = options.command;
+		const workspace = options.workspace;
+		const grace = options.grace;
+		const evidence = options.evidence;
+		const backlog = options.backlog;
+		const writable = options.writable;
+		const signal = options.signal;
 		const on = options.on;
 		const error = options.error;
+		const isolated = command.isolated;
+		const overrides = command.environment;
+		const input = command.input;
+		validateCommand(command);
+		validateWorkspace(workspace);
+		validateTimer(grace, "option 'grace'");
+		validateBytes(evidence, "option 'evidence'", 0);
+		validateBytes(backlog, "option 'backlog'", 1);
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			...on === void 0 ? {} : { on },
 			...error === void 0 ? {} : { error }
 		});
-		this.#grace = options.grace;
-		this.#limit = options.evidence ?? _src_core.PROCESS_EVIDENCE;
-		this.#signal = options.signal;
+		this.#grace = grace ?? _src_core.PROCESS_GRACE;
+		this.#evidence = evidence ?? _src_core.PROCESS_EVIDENCE;
+		this.#backlog = backlog ?? _src_core.PROCESS_BACKLOG;
+		this.#signal = signal;
 		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
-		this.#child = (0, node_child_process.spawn)(options.command.file, [...options.command.arguments], {
-			cwd: options.workspace,
+		const environment = mergeEnvironment(isolated === true, overrides);
+		const plan = buildSpawn(command, {
+			workspace,
+			environment
+		});
+		this.#child = (0, node_child_process.spawn)(plan.file, [...plan.arguments], {
+			cwd: workspace,
 			detached: process.platform !== "win32",
-			env: mergeEnvironment(options.command.environment),
+			env: environment,
 			stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
 			],
-			windowsHide: true
+			windowsHide: true,
+			windowsVerbatimArguments: plan.verbatim
 		});
 		this.#reader = (0, node_readline.createInterface)({
 			input: this.#child.stdout,
@@ -408,19 +951,19 @@ var Process = class {
 		this.#child.once("close", this.#close.bind(this));
 		this.#child.stdin.on("error", () => void 0);
 		this.#child.stderr.on("data", this.#retain.bind(this));
-		if (options.command.input !== void 0) this.#child.stdin.write(options.command.input);
-		if (options.writable !== true) this.#child.stdin.end();
-		if (this.#signal !== void 0) {
+		if (input !== void 0) this.#child.stdin.write(input);
+		if (writable !== true) this.#child.stdin.end();
+		if (signal !== void 0) {
 			this.#abort = this.#terminate.bind(this);
-			this.#signal.addEventListener("abort", this.#abort, { once: true });
-			if (this.#signal.aborted) this.stop();
+			signal.addEventListener("abort", this.#abort, { once: true });
+			if (signal.aborted) this.stop();
 		}
 	}
 	/** The typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The eagerly captured stdout lines, in arrival order, ending when the child's stdout closes. */
+	/** The captured stdout lines, in arrival order, ending when the child's stdout closes. */
 	get lines() {
 		return this.#lines;
 	}
@@ -435,21 +978,35 @@ var Process = class {
 	/**
 	* Write one line to the open standard-input channel.
 	*
+	* @remarks
+	* Never rejects. The promise settles when the host reports the line handled, so a line written to
+	* a child that is not reading stays pending until the child drains it or the channel closes. Every
+	* terminal teardown path destroys stdin, so a pending write always settles by teardown; a caller
+	* that needs its own deadline arms a timer and calls `stop`.
+	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the channel accepted the line without backpressure; false otherwise
+	* @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
 	*/
 	send(text) {
-		if (this.#closed || this.#child.stdin.destroyed || this.#child.stdin.writableEnded) return false;
+		const stdin = this.#child.stdin;
+		if (this.#closed || !stdin.writable) return Promise.resolve(false);
+		const settled = Promise.withResolvers();
 		try {
-			return this.#child.stdin.write(`${text}\n`);
+			stdin.write(`${text}\n`, (error) => {
+				settled.resolve(error === void 0 || error === null);
+			});
 		} catch {
-			return false;
+			return Promise.resolve(false);
 		}
+		return settled.promise;
 	}
 	/**
 	* Terminate the child process tree and await its observed exit.
 	*
-	* @returns A promise that resolves after bounded termination
+	* @remarks
+	* Never rejects, and every call shares one termination.
+	*
+	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
 	*/
 	stop() {
 		if (this.#stopping !== void 0) return this.#stopping;
@@ -457,7 +1014,10 @@ var Process = class {
 		return this.#stopping;
 	}
 	/**
-	* Stop the child and destroy the observation emitter.
+	* Stop the child, close its standard-input channel, and destroy the observation emitter.
+	*
+	* @remarks
+	* Always resolves, including when termination was never confirmed.
 	*
 	* @returns The stable barrier shared by every call
 	*/
@@ -467,10 +1027,11 @@ var Process = class {
 		return this.#ending;
 	}
 	#iterate() {
+		this.#requested = true;
 		return Object.freeze({ next: this.#next.bind(this) });
 	}
 	#next() {
-		const line = this.#buffer.shift();
+		const line = this.#take();
 		if (line !== void 0) return Promise.resolve(Object.freeze({
 			done: false,
 			value: line
@@ -483,21 +1044,52 @@ var Process = class {
 		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 -= node_buffer.Buffer.byteLength(line) + 1;
+		this.#relieve();
+		return line;
+	}
 	#push(line) {
 		if (this.#ended) return;
 		const waiter = this.#waiters.shift();
-		if (waiter === void 0) {
-			this.#buffer.push(line);
+		if (waiter !== void 0) {
+			waiter.resolve(Object.freeze({
+				done: false,
+				value: line
+			}));
 			return;
 		}
-		waiter.resolve(Object.freeze({
-			done: false,
-			value: line
-		}));
+		const bytes = node_buffer.Buffer.byteLength(line) + 1;
+		if (!this.#requested && this.#pending + bytes > this.#backlog) return;
+		this.#queue.push(line);
+		this.#pending += bytes;
+		this.#restrain();
+	}
+	#restrain() {
+		if (this.#paused || this.#terminating || !this.#requested) return;
+		if (this.#pending < this.#backlog) return;
+		this.#paused = true;
+		this.#reader.pause();
+	}
+	#relieve() {
+		if (!this.#paused || this.#ended) return;
+		if (!this.#terminating && 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
@@ -506,7 +1098,7 @@ var Process = class {
 	}
 	#retain(chunk) {
 		if (!node_buffer.Buffer.isBuffer(chunk) || this.#closed) return;
-		this.#tail = trimTail(node_buffer.Buffer.concat([this.#tail, chunk]), this.#limit);
+		this.#tail = trimTail(node_buffer.Buffer.concat([this.#tail, chunk]), this.#evidence);
 		const text = this.#decoder.write(chunk);
 		if (text.length > 0) this.#emitter.emit("stderr", text);
 	}
@@ -528,15 +1120,11 @@ var Process = class {
 		this.stop();
 	}
 	async #kill() {
-		if (this.#closed) return;
-		killProcess(this.#child, "SIGTERM");
-		const grace = Promise.withResolvers();
-		const timer = setTimeout(grace.resolve, this.#grace);
-		await Promise.race([this.#exit.promise, grace.promise]);
-		clearTimeout(timer);
-		if (this.#closed) return;
-		killProcess(this.#child, "SIGKILL");
-		await this.#exit.promise;
+		this.#terminating = true;
+		this.#relieve();
+		const confirmed = await stopChild(this.#child, this.#grace, _src_core.PROCESS_CONFIRMATION);
+		this.#child.stdin.destroy();
+		return confirmed;
 	}
 	async #teardown() {
 		await this.stop();
@@ -550,9 +1138,15 @@ var Process = class {
 *
 * @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. `launch` throws
-* a {@link createDuplicateError} when the id is already live — a spawn fault surfaces through the
-* returned child's `exit`, never from `launch`. `destroy` stops every child, then destroys the
+* 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, which destroys each
+* child's observation emitter and leaves every subscription on it silently inert, then destroys the
 * registry emitter last.
 *
 * @example
@@ -563,7 +1157,6 @@ var Process = class {
 * const child = manager.launch('build', {
 * 	command: { file: 'node', arguments: ['build.js'] },
 * 	workspace: process.cwd(),
-* 	grace: 5000,
 * })
 * await child.exit
 * await manager.destroy()
@@ -572,6 +1165,8 @@ var Process = class {
 var ProcessManager = class {
 	#emitter;
 	#children = /* @__PURE__ */ new Map();
+	#ids = /* @__PURE__ */ new Set();
+	#destroying = false;
 	#ending;
 	/**
 	* Construct a process registry.
@@ -614,16 +1209,31 @@ var ProcessManager = class {
 	/**
 	* Spawn and register one child under `id`.
 	*
+	* @remarks
+	* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
+	* nothing has started and a throw from one strands no process. A getter that begins `destroy`
+	* without throwing is the one remaining race, and it leaves a bounded residual: the child is
+	* already spawned, so the launch is refused with a {@link createProtocolError} and that child is
+	* torn down asynchronously, bounded by `grace` plus the confirmation window. The `destroy` barrier
+	* settled before the refusal, so awaiting it does not cover that teardown.
+	*
 	* @param id - The registry key, unique among live children
 	* @param options - The child construction options
 	* @returns The launched child
-	* @throws A {@link ProcessError} coded `duplicate` when `id` is already live
+	* @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, options) {
-		if (this.#children.has(id)) throw (0, _src_core.createDuplicateError)(id);
-		const child = new Process(options);
+		if (this.#destroying) throw (0, _src_core.createProtocolError)(id);
+		if (this.#ids.has(id)) throw (0, _src_core.createDuplicateError)(id);
+		this.#ids.add(id);
+		const child = this.#construct(id, options);
+		if (this.#destroying) {
+			this.#ids.delete(id);
+			child.destroy();
+			throw (0, _src_core.createProtocolError)(id);
+		}
 		this.#children.set(id, child);
-		child.emitter.on("exit", (exit) => this.#evict(id, child, exit));
+		child.exit.then((exit) => this.#evict(id, child, exit));
 		this.#emitter.emit("launch", id);
 		return child;
 	}
@@ -635,32 +1245,48 @@ var ProcessManager = class {
 	/**
 	* Stop every child, then destroy the registry emitter last.
 	*
+	* @remarks
+	* Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
+	* destroyed rather than merely stopped, so its own observation emitter is destroyed too and every
+	* subscription on it goes silently inert.
+	*
 	* @returns The stable barrier shared by every call
 	*/
 	destroy() {
 		if (this.#ending !== void 0) return this.#ending;
+		this.#destroying = true;
 		this.#ending = this.#teardown();
 		return this.#ending;
 	}
+	#construct(id, options) {
+		try {
+			return new Process(options);
+		} catch (error) {
+			this.#ids.delete(id);
+			throw error;
+		}
+	}
 	#evict(id, child, exit) {
 		if (this.#children.get(id) !== child) return;
 		this.#children.delete(id);
+		this.#ids.delete(id);
 		this.#emitter.emit("exit", id, exit);
 	}
 	async #stopOne(id) {
 		const child = this.#children.get(id);
 		if (child === void 0) return false;
-		await child.stop();
-		return true;
+		return child.stop();
 	}
 	async #stopMany(ids) {
 		return (await Promise.all(ids.map((id) => this.#stopOne(id)))).every((ok) => ok);
 	}
 	async #stopAll() {
-		await Promise.all([...this.#children.values()].map((child) => child.stop()));
+		await Promise.allSettled([...this.#children.values()].map((child) => child.stop()));
 	}
 	async #teardown() {
-		await Promise.all([...this.#children.values()].map((child) => child.destroy()));
+		await Promise.allSettled([...this.#children.values()].map((child) => child.destroy()));
+		this.#children.clear();
+		this.#ids.clear();
 		this.#emitter.destroy();
 	}
 };
@@ -706,15 +1332,31 @@ function createProcessManager(options) {
 exports.Process = Process;
 exports.ProcessManager = ProcessManager;
 exports.buildRunResult = buildRunResult;
-exports.commandLine = commandLine;
+exports.buildSpawn = buildSpawn;
 exports.createProcess = createProcess;
 exports.createProcessManager = createProcessManager;
+exports.detach = detach;
+exports.formatCommand = formatCommand;
+exports.isExited = isExited;
+exports.isFile = isFile;
 exports.killProcess = killProcess;
+exports.killTree = killTree;
 exports.mergeEnvironment = mergeEnvironment;
-exports.requiresShell = requiresShell;
+exports.quoteArgument = quoteArgument;
+exports.readVariable = readVariable;
+exports.resolveExecutable = resolveExecutable;
+exports.retainChunk = retainChunk;
 exports.run = run;
 exports.runSync = runSync;
+exports.stopChild = stopChild;
 exports.trimHead = trimHead;
 exports.trimTail = trimTail;
+exports.validateBytes = validateBytes;
+exports.validateCommand = validateCommand;
+exports.validateEnvironment = validateEnvironment;
+exports.validateText = validateText;
+exports.validateTimer = validateTimer;
+exports.validateWorkspace = validateWorkspace;
+exports.waitForExit = waitForExit;
 
 //# sourceMappingURL=index.cjs.map