@orkestrel/process 0.0.2 → 0.0.4

package/dist/src/server/index.js

@@ -1,39 +1,15 @@
 import { Buffer } from "node:buffer";
 import { spawn, spawnSync } from "node:child_process";
-import { extname } from "node:path";
-import { PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, createDuplicateError, createRunError } from "../core/index.js";
+import { statSync } from "node:fs";
+import { join, posix, win32 } from "node:path";
+import { platform } from "node:process";
+import { boundsOf, holds, isNonEmptyString, isNonNegativeInteger, isString } from "@orkestrel/contract";
+import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
 import { createInterface } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { Emitter } from "@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
@@ -41,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
 *
@@ -50,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 = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
 	if (buffer.byteLength <= limit) return buffer;
 	let start = buffer.byteLength - limit;
 	while (start < buffer.byteLength) {
@@ -68,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
 *
@@ -77,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 = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
 	if (buffer.byteLength <= limit) return buffer;
 	let end = limit;
 	while (end > 0) {
@@ -88,256 +66,630 @@ function trimHead(buffer, limit) {
 	return Buffer.from(buffer.subarray(0, end));
 }
 /**
-* Checks whether a command file must be spawned through a shell on the current host.
+* Takes one owned frozen snapshot of a caller's command.
 *
 * @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.
+* Every public entry point snapshots before it validates, so the object validated is the object
+* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
+* command whose `file` changes between reads would otherwise validate one executable and spawn
+* another. The argument vector and the environment record are copied and frozen, so a caller
+* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
+* becoming an explicit `undefined`.
 *
-* @param file - The command executable name or path
-* @returns True when the file must run through a shell; false when it spawns directly
+* @param command - The caller's command, whose properties may be getters
+* @returns A frozen command carrying the values read at this instant
 *
 * @example
 * ```ts
-* requiresShell('git') // true on Windows, false on POSIX
+* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
 * ```
 */
-function requiresShell(file) {
-	if (process.platform !== "win32") return false;
-	const lower = file.toLowerCase();
-	return lower.endsWith(".cmd") || lower.endsWith(".bat") || extname(file) === "";
+function snapshotCommand(command) {
+	const file = command.file;
+	const argumentsList = Object.freeze([...command.arguments]);
+	const sourceEnvironment = command.environment;
+	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
+	const input = command.input;
+	const isolated = command.isolated;
+	return Object.freeze({
+		file,
+		arguments: argumentsList,
+		...environment === void 0 ? {} : { environment },
+		...input === void 0 ? {} : { input },
+		...isolated === void 0 ? {} : { isolated }
+	});
 }
 /**
 * 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
+* @returns The space-joined command line, for an {@link ExecuteResult} and error messages
 *
 * @example
 * ```ts
-* commandLine({ file: 'git', arguments: ['status'] }) // 'git status'
+* formatCommand({ file: 'git', arguments: ['status'] }) // 'git status'
 * ```
 */
-function commandLine(command) {
+function formatCommand(command) {
 	return [command.file, ...command.arguments].join(" ");
 }
 /**
-* Merges environment overrides over the current process environment.
+* Reads one environment variable under an explicit platform's key rules.
 *
 * @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.
+* 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 for `win32`.
+*
+* @param environment - The environment record to read
+* @param name - The variable name
+* @param platform - The platform whose key rules apply
+* @returns The value, or `undefined` when the environment declares no such variable
 *
+* @example
+* ```ts
+* readPlatformVariable({ Path: 'C:\\Windows' }, 'PATH', 'win32') // 'C:\\Windows'
+* ```
+*/
+function readPlatformVariable(environment, name, platform) {
+	const direct = environment[name];
+	if (direct !== void 0) return direct;
+	if (platform !== "win32") return void 0;
+	const target = name.toUpperCase();
+	for (const [key, value] of Object.entries(environment)) if (key.toUpperCase() === target) return value;
+}
+/**
+* Reads one environment variable the way the current host resolves it.
+*
+* @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: '/usr/bin' }, 'PATH') // '/usr/bin'
+* ```
+*/
+function readVariable(environment, name) {
+	return readPlatformVariable(environment, name, platform);
+}
+/**
+* Merges environment layers under an explicit platform's key rules.
+*
+* @remarks
+* Later maps override earlier ones and an `undefined` value unsets a key. For `win32` 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 platform - The platform whose key rules apply
+* @param parent - The parent environment layer
+* @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 merged environment for a spawn
+* @returns The environment for a spawn, carrying no unset key
 *
 * @example
 * ```ts
-* mergeEnvironment({ TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+* mergePlatformEnvironment('linux', {}, false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
 * ```
 */
-function mergeEnvironment(base, override) {
-	return {
-		...process.env,
-		...base,
-		...override
-	};
+function mergePlatformEnvironment(platform, parent, isolated, base, override) {
+	const folded = platform === "win32";
+	const layers = [
+		isolated ? {} : parent,
+		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;
 }
 /**
-* Builds one settled {@link RunResult} from a completed one-shot run's captured bytes and exit.
+* Merges environment overrides into the environment one child receives on the current host.
+*
+* @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(true, { TOKEN: 'a' }) // { TOKEN: 'a' }
+* ```
+*/
+function mergeEnvironment(isolated, base, override) {
+	return mergePlatformEnvironment(platform, process.env, isolated, base, override);
+}
+/**
+* Checks whether a path names a regular file.
 *
 * @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
-* @returns The frozen run outcome
+* 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 holds(() => statSync(target, { throwIfNoEntry: false })?.isFile() === true);
+}
+/**
+* Builds the executable candidates an explicit platform would search.
+*
+* @remarks
+* Windows alone needs this list: 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 candidate list there is empty. 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. A non-Windows platform returns an empty list because `execvp` performs
+* its own lookup.
+*
+* @param file - The command executable name or path
+* @param workspace - The directory searched first
+* @param environment - The child's effective environment
+* @param platform - The platform whose lookup rules apply
+* @returns The ordered absolute candidate paths
+*
+* @example
+* ```ts
+* buildExecutableCandidates('git', 'C:\\work', { PATH: 'C:\\bin' }, 'win32')
+* ```
+*/
+function buildExecutableCandidates(file, workspace, environment, platform) {
+	if (platform !== "win32") return Object.freeze([]);
+	const candidates = [file, ...(readPlatformVariable(environment, "PATHEXT", platform) ?? PROCESS_PATHEXT).split(";").filter((extension) => extension.length > 0).map((extension) => `${file}${extension}`)];
+	const directories = file.includes("/") || file.includes("\\") ? [workspace] : [workspace, ...(readPlatformVariable(environment, "PATH", platform) ?? "").split(";")];
+	const targets = [];
+	for (const directory of directories) {
+		if (directory.length === 0) continue;
+		for (const candidate of candidates) targets.push(win32.resolve(directory, candidate));
+	}
+	return Object.freeze(targets);
+}
+/**
+* Resolves a command file to the executable path the host would launch.
+*
+* @param file - The command executable name or path
+* @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
-* buildRunResult('git status', Buffer.from('ok'), Buffer.alloc(0), 0, null, false, 1024)
+* resolveExecutable('git', {}) ?? 'git' // an absolute path on Windows, 'git' elsewhere
 * ```
 */
-function buildRunResult(command, stdout, stderr, code, signal, timedOut, limit) {
+function resolveExecutable(file, options) {
+	const environment = options?.environment ?? process.env;
+	const candidates = buildExecutableCandidates(file, options?.workspace ?? process.cwd(), environment, platform);
+	for (const target of candidates) if (isFile(target)) return target;
+}
+/**
+* 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. The quoted set includes `%`, although quoting cannot
+* stop `cmd.exe` expansion; {@link buildSpawn} therefore refuses `%` in an argument to a Windows
+* batch target.
+*
+* @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 a spawn form from a resolved file and an explicit platform.
+*
+* @remarks
+* 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
+* @param file - The resolved executable file
+* @param environment - The child's effective environment
+* @param platform - The platform whose batch rules apply
+* @returns The file, argument vector, and verbatim flag to spawn with
+* @throws A {@link ProcessError} coded `invalid` when `platform` is `win32`, the resolved target is a batch script, and an argument carries a percent sign
+*
+* @example
+* ```ts
+* buildPlatformSpawn({ file: 'node', arguments: ['--version'] }, 'node', {}, 'linux').verbatim // false
+* ```
+*/
+function buildPlatformSpawn(command, file, environment, platform) {
+	const extension = (platform === "win32" ? win32.extname(file) : posix.extname(file)).toLowerCase();
+	if (!(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 createInvalidError("command argument", argument);
+	const line = [`"${file}"`, ...command.arguments.map(quoteArgument)].join(" ");
 	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
+		file: readPlatformVariable(environment, "ComSpec", platform) ?? "cmd.exe",
+		arguments: Object.freeze([
+			"/d",
+			"/s",
+			"/c",
+			`"${line}"`
+		]),
+		verbatim: true
 	});
 }
 /**
-* Runs one command to completion, buffering its output, and settles with the outcome.
+* Builds the resolved spawn form of one command for the current host.
+*
+* @param command - The executable and its argument vector
+* @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
+* buildSpawn({ file: 'node', arguments: ['--version'] }).verbatim // false
+* ```
+*/
+function buildSpawn(command, options) {
+	return buildPlatformSpawn(command, resolveExecutable(command.file, options) ?? command.file, options?.environment ?? process.env, platform);
+}
+/**
+* Validates one spawn-bound string.
 *
 * @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}.
+* 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 command - The executable, arguments, and optional environment and input
-* @param options - Working directory, timeout, grace, signal, capture limit, and reject behavior
-* @returns The settled run outcome
-* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+* @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 (!isString(value) || value.includes("\0")) throw createInvalidError(subject, value);
+	if (required && !isNonEmptyString(value)) throw 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 (!isNonNegativeInteger(value) || !boundsOf(0, PROCESS_TIMER)(value)) throw 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 (!isNonNegativeInteger(value) || !boundsOf(minimum, Number.MAX_SAFE_INTEGER)(value)) throw 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);
+}
+/**
+* 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. When no group owns the pid and the host reports `ESRCH`, the
+* signal falls back to the child directly. On Windows, or when no pid is available, the signal also
+* goes to the child directly. Every other 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
-* const result = await run({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+* killProcess(child, 'SIGTERM')
 * ```
 */
-async function run(command, options) {
-	const limit = options?.limit ?? PROCESS_OUTPUT;
-	const grace = options?.grace ?? PROCESS_GRACE;
-	const timeout = options?.timeout ?? 0;
-	const reject = options?.reject ?? true;
-	const input = options?.input ?? command.input;
-	const line = commandLine(command);
+function killProcess(child, signal) {
+	try {
+		if (process.platform === "win32" || child.pid === void 0) {
+			child.kill(signal);
+			return;
+		}
+		process.kill(-child.pid, signal);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+			holds(() => child.kill(signal));
+			return;
+		}
+	}
+}
+/**
+* Kills one Windows process tree through `taskkill`.
+*
+* @remarks
+* 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 terminate = new AbortController();
-	const cleanup = new AbortController();
-	let stdout = Buffer.alloc(0);
-	let stderr = Buffer.alloc(0);
-	let timedOut = false;
-	let launchCause;
-	let killTimer;
-	let timeoutTimer;
-	let done = false;
-	const child = spawn(command.file, [...command.arguments], {
-		cwd: options?.workspace ?? process.cwd(),
-		detached: process.platform !== "win32",
-		env: mergeEnvironment(command.environment, options?.environment),
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		shell: requiresShell(command.file),
-		windowsHide: true
-	});
-	terminate.signal.addEventListener("abort", () => {
-		killProcess(child, "SIGTERM");
-		killTimer = setTimeout(() => killProcess(child, "SIGKILL"), grace);
-	}, { once: true });
-	child.stdin.on("error", () => void 0);
-	child.stdout.on("data", (chunk) => {
-		if (Buffer.isBuffer(chunk)) stdout = trimHead(Buffer.concat([stdout, chunk]), limit);
-	});
-	child.stderr.on("data", (chunk) => {
-		if (Buffer.isBuffer(chunk)) stderr = trimHead(Buffer.concat([stderr, chunk]), limit);
-	});
-	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));
+	const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe");
+	const killer = spawn(executable, [
+		"/F",
+		"/T",
+		"/PID",
+		String(pid)
+	], {
+		stdio: "ignore",
+		windowsHide: true,
+		timeout
 	});
-	if (input !== void 0) child.stdin.write(input);
-	child.stdin.end();
-	if (timeout > 0) timeoutTimer = setTimeout(() => {
-		timedOut = true;
-		terminate.abort();
+	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(() => {
+		child.off("exit", settled.resolve);
+		settled.resolve();
 	}, timeout);
-	if (options?.signal !== void 0) {
-		const signal = options.signal;
-		signal.addEventListener("abort", () => terminate.abort(), {
-			once: true,
-			signal: cleanup.signal
-		});
-		if (signal.aborted) terminate.abort();
+	child.once("exit", settled.resolve);
+	return settled.promise.finally(() => clearTimeout(timer));
+}
+/**
+* Terminates one child process tree and reports whether its native exit was observed.
+*
+* @remarks
+* Windows ends the whole tree at once through {@link killTree}, falling back to a direct kill after
+* the utility fails, because the host has no cooperative termination to offer. A POSIX host signals
+* the process group `SIGTERM`, falls back to the direct child when no group owns its pid, waits
+* `grace`, then sends `SIGKILL` through the same route. No signal is initiated after 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");
 	}
-	const result = await settled.promise;
-	if (result.failed && reject) throw createRunError(result, launchCause);
-	return result;
+	if (isExited(child)) return true;
+	await waitForExit(child, confirm);
+	return isExited(child);
 }
 /**
-* Runs one command to completion synchronously, buffering its output, and returns the outcome.
+* Builds one settled {@link ExecuteResult} from a completed run's captured bytes and terminal facts.
 *
 * @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}.
+* `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. Each byte field is bounded by `limit` on a code-point boundary here, which is the one
+* place the captured bytes are decoded.
 *
-* @param command - The executable, arguments, and optional environment and input
-* @param options - Working directory, timeout, signal, capture limit, and reject behavior
-* @returns The run outcome
-* @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+* @param input - The captured bytes, terminal state, and capture limit
+* @returns The frozen run outcome
 *
 * @example
 * ```ts
-* const result = runSync({ file: 'git', arguments: ['--version'] }, { reject: false })
+* buildExecuteResult({
+* 	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 runSync(command, options) {
-	const limit = options?.limit ?? PROCESS_OUTPUT;
-	const timeout = options?.timeout ?? 0;
-	const reject = options?.reject ?? true;
-	const input = options?.input ?? command.input;
-	const line = commandLine(command);
-	const outcome = spawnSync(command.file, [...command.arguments], {
-		cwd: options?.workspace ?? process.cwd(),
-		env: mergeEnvironment(command.environment, options?.environment),
-		encoding: "buffer",
-		maxBuffer: limit,
-		shell: requiresShell(command.file),
-		windowsHide: true,
-		...input !== void 0 ? { input } : {},
-		...options?.signal !== void 0 ? { signal: options.signal } : {},
-		...timeout > 0 ? {
-			timeout,
-			killSignal: "SIGKILL"
-		} : {}
+function buildExecuteResult(input) {
+	return Object.freeze({
+		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
 	});
-	const error = outcome.error;
-	const timedOut = error !== void 0 && "code" in error && error.code === "ETIMEDOUT";
-	const result = buildRunResult(line, Buffer.isBuffer(outcome.stdout) ? outcome.stdout : Buffer.alloc(0), Buffer.isBuffer(outcome.stderr) ? outcome.stderr : Buffer.alloc(0), outcome.status, outcome.signal, timedOut, limit);
-	if (result.failed && reject) throw createRunError(result, outcome.error);
-	return result;
 }
 //#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
-* 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.
+* Standard output is framed through `readline` into a single-consumer stream: each line goes to
+* exactly one waiting iterator, so concurrent 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. After an iterator
+* has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
+* nothing before termination and the child feels real backpressure. The mark is soft — the ordinary backlog can
+* overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
+* reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
+* and `truncated` reports the omission. 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. `pid`,
+* `code`, and `signal` read the spawned child directly, so the native exit is readable before the
+* `exit` promise settles on stdio close. `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
@@ -346,7 +698,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()
@@ -357,45 +708,74 @@ var Process = class {
 	#child;
 	#reader;
 	#grace;
-	#limit;
+	#evidence;
+	#backlog;
 	#decoder = new StringDecoder("utf8");
 	#exit = Promise.withResolvers();
 	#lines;
-	#buffer = [];
+	#queue = [];
 	#waiters = [];
 	#signal;
 	#abort;
 	#tail = Buffer.alloc(0);
+	#head = 0;
+	#pending = 0;
+	#requested = false;
+	#paused = false;
+	#truncated = 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 source = 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 command = snapshotCommand(source);
+		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 Emitter({
 			...on === void 0 ? {} : { on },
 			...error === void 0 ? {} : { error }
 		});
-		this.#grace = options.grace;
-		this.#limit = options.evidence ?? PROCESS_EVIDENCE;
-		this.#signal = options.signal;
+		this.#grace = grace ?? PROCESS_GRACE;
+		this.#evidence = evidence ?? PROCESS_EVIDENCE;
+		this.#backlog = backlog ?? PROCESS_BACKLOG;
+		this.#signal = signal;
 		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
-		this.#child = spawn(options.command.file, [...options.command.arguments], {
-			cwd: options.workspace,
+		const childEnvironment = mergeEnvironment(command.isolated === true, command.environment);
+		const plan = buildSpawn(command, {
+			workspace,
+			environment: childEnvironment
+		});
+		this.#child = spawn(plan.file, [...plan.arguments], {
+			cwd: workspace,
 			detached: process.platform !== "win32",
-			env: mergeEnvironment(options.command.environment),
+			env: childEnvironment,
 			stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
 			],
-			windowsHide: true
+			windowsHide: true,
+			windowsVerbatimArguments: plan.verbatim
 		});
 		this.#reader = createInterface({
 			input: this.#child.stdout,
@@ -407,19 +787,31 @@ 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 host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	get pid() {
+		return this.#child.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.#child.exitCode;
+	}
+	/** 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.#child.signalCode;
+	}
 	/** 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;
 	}
@@ -427,6 +819,10 @@ var Process = class {
 	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;
+	}
 	/** The terminal child state, observed once from the close event. */
 	get exit() {
 		return this.#exit.promise;
@@ -434,21 +830,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;
@@ -456,7 +866,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
 	*/
@@ -466,10 +879,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
@@ -482,21 +896,56 @@ 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 -= 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 = Buffer.byteLength(line) + 1;
+		const limit = this.#terminating ? this.#backlog * 2 : this.#backlog;
+		if ((!this.#requested || this.#terminating) && this.#pending + bytes > limit) {
+			this.#truncated = true;
+			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
@@ -505,7 +954,7 @@ var Process = class {
 	}
 	#retain(chunk) {
 		if (!Buffer.isBuffer(chunk) || this.#closed) return;
-		this.#tail = trimTail(Buffer.concat([this.#tail, chunk]), this.#limit);
+		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);
 	}
@@ -514,7 +963,7 @@ var Process = class {
 		const suffix = this.#decoder.end();
 		if (suffix.length > 0) this.#emitter.emit("stderr", suffix);
 		this.#closed = true;
-		if (this.#signal !== void 0 && this.#abort !== void 0) this.#signal.removeEventListener("abort", this.#abort);
+		this.#removeAbortListener();
 		this.#reader.close();
 		const exit = Object.freeze({
 			code,
@@ -526,18 +975,29 @@ var Process = class {
 	#terminate() {
 		this.stop();
 	}
+	#removeAbortListener() {
+		if (this.#signal === void 0 || this.#abort === void 0) return;
+		this.#signal.removeEventListener("abort", this.#abort);
+	}
+	#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() {
-		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.#capBacklog();
+		this.#relieve();
+		const confirmed = await stopChild(this.#child, this.#grace, PROCESS_CONFIRMATION);
+		this.#child.stdin.destroy();
+		return confirmed;
 	}
 	async #teardown() {
+		this.#removeAbortListener();
 		await this.stop();
 		this.#emitter.destroy();
 	}
@@ -549,9 +1009,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
@@ -562,7 +1028,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()
@@ -571,6 +1036,8 @@ var Process = class {
 var ProcessManager = class {
 	#emitter;
 	#children = /* @__PURE__ */ new Map();
+	#ids = /* @__PURE__ */ new Set();
+	#destroying = false;
 	#ending;
 	/**
 	* Construct a process registry.
@@ -613,16 +1080,32 @@ 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 `protocol`
+	* refusal throws synchronously before the `destroy` barrier settles. The barrier does not cover
+	* that child's asynchronous 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 createDuplicateError(id);
-		const child = new Process(options);
+		if (this.#destroying) throw createProtocolError(id);
+		if (this.#ids.has(id)) throw createDuplicateError(id);
+		this.#ids.add(id);
+		const child = this.#construct(id, options);
+		if (this.#destroying) {
+			this.#ids.delete(id);
+			child.destroy();
+			throw 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;
 	}
@@ -634,32 +1117,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();
 	}
 };
@@ -702,6 +1201,318 @@ function createProcessManager(options) {
 	return new ProcessManager(options);
 }
 //#endregion
-export { Process, ProcessManager, buildRunResult, commandLine, createProcess, createProcessManager, killProcess, mergeEnvironment, requiresShell, run, runSync, trimHead, trimTail };
+//#region src/server/Retention.ts
+/**
+* Accumulates byte totals while retaining a bounded stream head.
+*
+* @example
+* ```ts
+* const retention = new Retention()
+* retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
+* retention.retained // 3
+* ```
+*/
+var Retention = class {
+	#delivered = 0;
+	#retained = 0;
+	/** The bytes delivered by the stream. */
+	get delivered() {
+		return this.#delivered;
+	}
+	/** The bytes retained from the stream head. */
+	get retained() {
+		return this.#retained;
+	}
+	/**
+	* Retains a delivered chunk within a byte limit.
+	*
+	* @param chunk - The delivered chunk, ignored when it is not a buffer
+	* @param limit - The maximum retained byte count
+	* @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
+	*/
+	retain(chunk, limit) {
+		if (!Buffer.isBuffer(chunk)) return void 0;
+		this.#delivered += chunk.byteLength;
+		const room = limit - this.#retained;
+		if (room <= 0) return void 0;
+		const slice = chunk.byteLength <= room ? chunk : Buffer.from(chunk.subarray(0, room));
+		this.#retained += slice.byteLength;
+		return slice;
+	}
+};
+//#endregion
+//#region src/server/execution/execute.ts
+/**
+* Runs one command to completion, buffering its output, and settles with the outcome.
+*
+* @remarks
+* 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 earliest is recorded: a timeout reports
+* `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
+* a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
+* 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 createExecuteError} carrying the {@link ExecuteResult}. 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 failure delivery
+* @returns The settled run outcome
+* @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link ExecuteResult} when the run failed and `strict` is not `false`
+*
+* @example
+* ```ts
+* const result = await execute({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+* ```
+*/
+async function execute(command, options) {
+	const snapshot = snapshotCommand(command);
+	const optionEnvironment = options?.environment;
+	const optionWorkspace = options?.workspace;
+	const optionInput = options?.input;
+	const optionTimeout = options?.timeout;
+	const optionGrace = options?.grace;
+	const optionSignal = options?.signal;
+	const optionStrict = options?.strict;
+	const optionLimit = options?.limit;
+	validateCommand(snapshot);
+	validateEnvironment(optionEnvironment);
+	validateWorkspace(optionWorkspace);
+	validateTimer(optionTimeout, "option 'timeout'");
+	validateTimer(optionGrace, "option 'grace'");
+	validateBytes(optionLimit, "option 'limit'", 0);
+	const limit = optionLimit ?? PROCESS_OUTPUT;
+	const grace = optionGrace ?? PROCESS_GRACE;
+	const timeout = optionTimeout ?? 0;
+	const strict = optionStrict ?? true;
+	const text = optionInput ?? snapshot.input;
+	const line = formatCommand(snapshot);
+	const workspace = optionWorkspace ?? process.cwd();
+	const environment = mergeEnvironment(snapshot.isolated === true, snapshot.environment, optionEnvironment);
+	const plan = buildSpawn(snapshot, {
+		workspace,
+		environment
+	});
+	const settled = Promise.withResolvers();
+	const terminate = new AbortController();
+	const cleanup = new AbortController();
+	const finish = new AbortController();
+	const outChunks = [];
+	const errChunks = [];
+	const outRetention = new Retention();
+	const errRetention = new Retention();
+	let spawned = false;
+	let expired = false;
+	let aborted = false;
+	let cause;
+	let timeoutTimer;
+	let confirmTimer;
+	const child = spawn(plan.file, [...plan.arguments], {
+		cwd: workspace,
+		detached: process.platform !== "win32",
+		env: environment,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true,
+		windowsVerbatimArguments: plan.verbatim
+	});
+	finish.signal.addEventListener("abort", () => {
+		clearTimeout(timeoutTimer);
+		clearTimeout(confirmTimer);
+		cleanup.abort();
+		settled.resolve(buildExecuteResult({
+			command: line,
+			stdout: Buffer.concat(outChunks),
+			stderr: Buffer.concat(errChunks),
+			code: child.exitCode,
+			signal: child.signalCode,
+			expired,
+			aborted,
+			truncated: outRetention.delivered > limit || errRetention.delivered > limit,
+			limit,
+			...cause === void 0 ? {} : { cause }
+		}));
+	}, { once: true });
+	terminate.signal.addEventListener("abort", () => {
+		clearTimeout(timeoutTimer);
+		cleanup.abort();
+		stopChild(child, grace, PROCESS_CONFIRMATION).then(() => {
+			if (finish.signal.aborted) return;
+			confirmTimer = setTimeout(() => finish.abort(), PROCESS_CONFIRMATION);
+		});
+	}, { once: true });
+	child.stdin.on("error", () => void 0);
+	child.stdout.on("data", (chunk) => {
+		const retained = outRetention.retain(chunk, limit);
+		if (retained !== void 0) outChunks.push(retained);
+	});
+	child.stderr.on("data", (chunk) => {
+		const retained = errRetention.retain(chunk, limit);
+		if (retained !== void 0) errChunks.push(retained);
+	});
+	child.once("spawn", () => {
+		spawned = true;
+	});
+	child.once("error", (error) => {
+		if (spawned) return;
+		cause = error;
+		finish.abort();
+	});
+	child.once("close", () => finish.abort());
+	if (text !== void 0) child.stdin.write(text);
+	child.stdin.end();
+	if (timeout > 0) timeoutTimer = setTimeout(() => {
+		expired = true;
+		terminate.abort();
+	}, timeout);
+	if (optionSignal !== void 0) {
+		optionSignal.addEventListener("abort", () => {
+			aborted = true;
+			terminate.abort();
+		}, {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (optionSignal.aborted) {
+			aborted = true;
+			terminate.abort();
+		}
+	}
+	const result = await settled.promise;
+	if (result.failed && strict) throw createExecuteError(result, cause);
+	return result;
+}
+//#endregion
+//#region src/server/execution/executeSync.ts
+/**
+* Runs one command to completion synchronously, buffering its output, and returns the outcome.
+*
+* @remarks
+* The synchronous counterpart of {@link execute}, 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` ends only the root process and can leave
+* descendants running; use {@link execute} or {@link Process} when timeout must terminate the tree. A
+* timeout and an output overflow both end the root with `SIGKILL`: an overflow reports `truncated`
+* and `failed` together and trims the partial output to `limit`, where {@link execute} keeps reading and
+* reports `truncated` without failing. The environment and input follow the same merge as
+* {@link execute}. Unless `strict` is `false`, a failed run throws a {@link createExecuteError}
+* carrying the {@link ExecuteResult}.
+*
+* @param command - The executable, arguments, and optional environment and input
+* @param options - Working directory, timeout, capture limit, and failure delivery
+* @returns The run outcome
+* @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link ExecuteResult} when the run failed and `strict` is not `false`
+*
+* @example
+* ```ts
+* const result = executeSync({ file: 'git', arguments: ['--version'] }, { strict: false })
+* ```
+*/
+function executeSync(command, options) {
+	const snapshot = snapshotCommand(command);
+	const optionEnvironment = options?.environment;
+	const optionWorkspace = options?.workspace;
+	const optionInput = options?.input;
+	const optionTimeout = options?.timeout;
+	const optionStrict = options?.strict;
+	const optionLimit = options?.limit;
+	validateCommand(snapshot);
+	validateEnvironment(optionEnvironment);
+	validateWorkspace(optionWorkspace);
+	validateTimer(optionTimeout, "option 'timeout'");
+	validateBytes(optionLimit, "option 'limit'", 0);
+	const limit = optionLimit ?? PROCESS_OUTPUT;
+	const timeout = optionTimeout ?? 0;
+	const strict = optionStrict ?? true;
+	const text = optionInput ?? snapshot.input;
+	const line = formatCommand(snapshot);
+	const workspace = optionWorkspace ?? process.cwd();
+	const environment = mergeEnvironment(snapshot.isolated === true, snapshot.environment, optionEnvironment);
+	const plan = buildSpawn(snapshot, {
+		workspace,
+		environment
+	});
+	const outcome = spawnSync(plan.file, [...plan.arguments], {
+		cwd: workspace,
+		env: environment,
+		encoding: "buffer",
+		maxBuffer: limit,
+		killSignal: "SIGKILL",
+		windowsHide: true,
+		windowsVerbatimArguments: plan.verbatim,
+		...text !== void 0 ? { input: Buffer.from(text) } : {},
+		...timeout > 0 ? { timeout } : {}
+	});
+	const error = outcome.error;
+	const fault = error !== void 0 && "code" in error && isString(error.code) ? error.code : "";
+	const result = buildExecuteResult({
+		command: line,
+		stdout: Buffer.isBuffer(outcome.stdout) ? outcome.stdout : Buffer.alloc(0),
+		stderr: Buffer.isBuffer(outcome.stderr) ? outcome.stderr : 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 createExecuteError(result, error);
+	return result;
+}
+//#endregion
+//#region src/server/execution/detach.ts
+/**
+* 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) {
+	const snapshot = snapshotCommand(command);
+	const optionWorkspace = options?.workspace;
+	validateCommand(snapshot);
+	validateWorkspace(optionWorkspace);
+	const workspace = optionWorkspace ?? process.cwd();
+	const environment = mergeEnvironment(snapshot.isolated === true, snapshot.environment);
+	const plan = buildSpawn(snapshot, {
+		workspace,
+		environment
+	});
+	const child = 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
+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, waitForExit };
 
 //# sourceMappingURL=index.js.map