@orkestrel/process 0.0.3 → 0.0.5

package/dist/src/server/index.cjs

@@ -3,6 +3,7 @@ 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 node_process = require("node:process");
 let _orkestrel_contract = require("@orkestrel/contract");
 let _src_core = require("../core/index.cjs");
 let node_readline = require("node:readline");
@@ -66,10 +67,44 @@ function trimHead(bytes, limit) {
 	return node_buffer.Buffer.from(buffer.subarray(0, end));
 }
 /**
+* Takes one owned frozen snapshot of a caller's command.
+*
+* @remarks
+* 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 command - The caller's command, whose properties may be getters
+* @returns A frozen command carrying the values read at this instant
+*
+* @example
+* ```ts
+* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
+* ```
+*/
+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
@@ -80,36 +115,54 @@ function formatCommand(command) {
 	return [command.file, ...command.arguments].join(" ");
 }
 /**
-* Reads one environment variable the way the host resolves it.
+* Reads one environment variable under an explicit platform's key rules.
 *
 * @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.
+* 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
-* readVariable({ Path: 'C:\\Windows' }, 'PATH') // 'C:\\Windows' on Windows
+* readPlatformVariable({ Path: 'C:\\Windows' }, 'PATH', 'win32') // 'C:\\Windows'
 * ```
 */
-function readVariable(environment, name) {
+function readPlatformVariable(environment, name, platform) {
 	const direct = environment[name];
 	if (direct !== void 0) return direct;
-	if (process.platform !== "win32") return void 0;
+	if (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.
+* 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, node_process.platform);
+}
+/**
+* Merges environment layers under an explicit platform's key rules.
 *
 * @remarks
-* Later maps override earlier ones and an `undefined` value unsets a key. On Windows the keys fold
+* 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
@@ -117,13 +170,13 @@ function readVariable(environment, name) {
 *
 * @example
 * ```ts
-* mergeEnvironment(false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+* mergePlatformEnvironment('linux', {}, false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
 * ```
 */
-function mergeEnvironment(isolated, base, override) {
-	const folded = process.platform === "win32";
+function mergePlatformEnvironment(platform, parent, isolated, base, override) {
+	const folded = platform === "win32";
 	const layers = [
-		isolated ? {} : process.env,
+		isolated ? {} : parent,
 		base ?? {},
 		override ?? {}
 	];
@@ -141,6 +194,22 @@ function mergeEnvironment(isolated, base, override) {
 	return merged;
 }
 /**
+* 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(node_process.platform, process.env, isolated, base, override);
+}
+/**
 * Checks whether a path names a regular file.
 *
 * @remarks
@@ -159,18 +228,44 @@ 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.
+* Builds the executable candidates an explicit platform would search.
 *
 * @remarks
-* Windows alone needs this: the host searches the working directory before `PATH` and applies
+* 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 answer there is always `undefined`. An appended extension is spelled the way
+* 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.
+* 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) ?? _src_core.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(node_path.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
@@ -182,18 +277,9 @@ function isFile(target) {
 * ```
 */
 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;
-		}
-	}
+	const candidates = buildExecutableCandidates(file, options?.workspace ?? process.cwd(), environment, node_process.platform);
+	for (const target of candidates) if (isFile(target)) return target;
 }
 /**
 * Quotes one command-line token for a `cmd.exe` command line.
@@ -201,8 +287,9 @@ function resolveExecutable(file, options) {
 * @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.
+* 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
@@ -217,41 +304,41 @@ function quoteArgument(value) {
 	return `"${value.replaceAll("\"", "\"\"")}"`;
 }
 /**
-* Builds the resolved spawn form of one command.
+* Builds a spawn form from a resolved file and an explicit platform.
 *
 * @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.
+* 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 options - The directory searched first and the child's effective environment
+* @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 the host is Windows, the resolved target is a batch script, and an argument carries a percent sign
+* @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
-* buildSpawn({ file: 'node', arguments: ['--version'] }).verbatim // false
+* buildPlatformSpawn({ file: 'node', arguments: ['--version'] }, 'node', {}, 'linux').verbatim // false
 * ```
 */
-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({
+function buildPlatformSpawn(command, file, environment, platform) {
+	const extension = (platform === "win32" ? node_path.win32.extname(file) : node_path.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 (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",
+		file: readPlatformVariable(environment, "ComSpec", platform) ?? "cmd.exe",
 		arguments: Object.freeze([
 			"/d",
 			"/s",
@@ -262,6 +349,22 @@ function buildSpawn(command, options) {
 	});
 }
 /**
+* 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, node_process.platform);
+}
+/**
 * Validates one spawn-bound string.
 *
 * @remarks
@@ -379,40 +482,6 @@ function validateWorkspace(workspace) {
 	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
@@ -436,10 +505,11 @@ function isExited(child) {
 *
 * @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.
+* 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
@@ -457,7 +527,12 @@ function killProcess(child, signal) {
 			return;
 		}
 		process.kill(-child.pid, signal);
-	} catch {}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+			(0, _orkestrel_contract.holds)(() => child.kill(signal));
+			return;
+		}
+	}
 }
 /**
 * Kills one Windows process tree through `taskkill`.
@@ -510,24 +585,25 @@ function killTree(pid, timeout) {
 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);
+	const timer = setTimeout(() => {
+		child.off("exit", settled.resolve);
 		settled.resolve();
-	});
-	return settled.promise;
+	}, timeout);
+	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 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.
+* 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`
@@ -553,12 +629,12 @@ async function stopChild(child, grace, confirm) {
 	return isExited(child);
 }
 /**
-* Builds one settled {@link RunResult} from a completed run's captured bytes and terminal facts.
+* Builds one settled {@link ExecuteResult} 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
+* 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 input - The captured bytes, terminal state, and capture limit
@@ -566,7 +642,7 @@ async function stopChild(child, grace, confirm) {
 *
 * @example
 * ```ts
-* buildRunResult({
+* buildExecuteResult({
 * 	command: 'git status',
 * 	stdout: Buffer.from('ok'),
 * 	stderr: Buffer.alloc(0),
@@ -579,7 +655,7 @@ async function stopChild(child, grace, confirm) {
 * }).failed // false
 * ```
 */
-function buildRunResult(input) {
+function buildExecuteResult(input) {
 	return Object.freeze({
 		command: input.command,
 		stdout: trimHead(input.stdout, input.limit).toString("utf8"),
@@ -592,247 +668,6 @@ function buildRunResult(input) {
 		truncated: input.truncated
 	});
 }
-/**
-* 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 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 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 RunResult} when the run failed and `strict` is not `false`
-*
-* @example
-* ```ts
-* const result = await run({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
-* ```
-*/
-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 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();
-	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 confirmTimer;
-	const child = (0, node_child_process.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(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", () => {
-		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) => retainChunk(chunk, outChunks, outCounts, limit));
-	child.stderr.on("data", (chunk) => retainChunk(chunk, errChunks, errCounts, limit));
-	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 (options?.signal !== void 0) {
-		const signal = options.signal;
-		signal.addEventListener("abort", () => {
-			aborted = true;
-			terminate.abort();
-		}, {
-			once: true,
-			signal: cleanup.signal
-		});
-		if (signal.aborted) {
-			aborted = true;
-			terminate.abort();
-		}
-	}
-	const result = await settled.promise;
-	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}, 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, 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 RunResult} when the run failed and `strict` is not `false`
-*
-* @example
-* ```ts
-* 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 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,
-		killSignal: "SIGKILL",
-		windowsHide: true,
-		windowsVerbatimArguments: plan.verbatim,
-		...text !== void 0 ? { input: text } : {},
-		...timeout > 0 ? { timeout } : {}
-	});
-	const error = 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
 /**
@@ -840,20 +675,25 @@ function detach(command, options) {
 *
 * @remarks
 * 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
+* 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 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` 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.
+* 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 a
+* child `error` cause on a spawn fault, a `protocol` {@link ProcessError} on a host-reported stdin
+* fault after the constructor input phase, and the terminal `exit`, alongside the `exit` promise.
+* A fault arising from the constructor-supplied `input` write or its closing `end` stays quiet
+* because the package initiated that sequence. `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
@@ -874,6 +714,7 @@ var Process = class {
 	#grace;
 	#evidence;
 	#backlog;
+	#delivery;
 	#decoder = new node_string_decoder.StringDecoder("utf8");
 	#exit = Promise.withResolvers();
 	#lines;
@@ -881,14 +722,18 @@ var Process = class {
 	#waiters = [];
 	#signal;
 	#abort;
+	#writes = /* @__PURE__ */ new Map();
 	#tail = node_buffer.Buffer.alloc(0);
 	#head = 0;
 	#pending = 0;
 	#requested = false;
 	#paused = false;
+	#truncated = false;
 	#terminating = false;
 	#closed = false;
 	#ended = false;
+	#input = 0;
+	#failure;
 	#stopping;
 	#ending;
 	/**
@@ -898,21 +743,22 @@ var Process = class {
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
 	*/
 	constructor(options) {
-		const command = options.command;
+		const source = options.command;
 		const workspace = options.workspace;
 		const grace = options.grace;
 		const evidence = options.evidence;
 		const backlog = options.backlog;
+		const delivery = options.delivery;
 		const writable = options.writable;
 		const signal = options.signal;
 		const on = options.on;
 		const error = options.error;
-		const isolated = command.isolated;
-		const overrides = command.environment;
+		const command = snapshotCommand(source);
 		const input = command.input;
 		validateCommand(command);
 		validateWorkspace(workspace);
 		validateTimer(grace, "option 'grace'");
+		validateTimer(delivery, "option 'delivery'");
 		validateBytes(evidence, "option 'evidence'", 0);
 		validateBytes(backlog, "option 'backlog'", 1);
 		this.#emitter = new _orkestrel_emitter.Emitter({
@@ -922,17 +768,18 @@ var Process = class {
 		this.#grace = grace ?? _src_core.PROCESS_GRACE;
 		this.#evidence = evidence ?? _src_core.PROCESS_EVIDENCE;
 		this.#backlog = backlog ?? _src_core.PROCESS_BACKLOG;
+		this.#delivery = delivery ?? 0;
 		this.#signal = signal;
 		this.#lines = Object.freeze({ [Symbol.asyncIterator]: this.#iterate.bind(this) });
-		const environment = mergeEnvironment(isolated === true, overrides);
+		const childEnvironment = mergeEnvironment(command.isolated === true, command.environment);
 		const plan = buildSpawn(command, {
 			workspace,
-			environment
+			environment: childEnvironment
 		});
 		this.#child = (0, node_child_process.spawn)(plan.file, [...plan.arguments], {
 			cwd: workspace,
 			detached: process.platform !== "win32",
-			env: environment,
+			env: childEnvironment,
 			stdio: [
 				"pipe",
 				"pipe",
@@ -949,16 +796,34 @@ var Process = class {
 		this.#reader.once("close", this.#finish.bind(this));
 		this.#child.once("error", (cause) => this.#emitter.emit("error", cause));
 		this.#child.once("close", this.#close.bind(this));
-		this.#child.stdin.on("error", () => void 0);
+		this.#child.stdin.on("error", (cause) => this.#failInputStream(cause));
 		this.#child.stderr.on("data", this.#retain.bind(this));
-		if (input !== void 0) this.#child.stdin.write(input);
-		if (writable !== true) this.#child.stdin.end();
+		if (input !== void 0) {
+			this.#input += 1;
+			this.#child.stdin.write(input, this.#completeInput.bind(this));
+		}
+		if (writable !== true) {
+			this.#input += 1;
+			this.#child.stdin.end(this.#completeInput.bind(this));
+		}
 		if (signal !== void 0) {
 			this.#abort = this.#terminate.bind(this);
 			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;
@@ -971,6 +836,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;
@@ -979,24 +848,34 @@ 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`.
+	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
+	* prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
+	* full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
+	* terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
+	* 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
+	* the write can settle `true` without a callback error or a stream error while the child remains
+	* alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
+	* that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
+	* for bytes the package is about to discard.
 	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
+	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
 	*/
 	send(text) {
 		const stdin = this.#child.stdin;
-		if (this.#closed || !stdin.writable) return Promise.resolve(false);
+		if (this.#closed || this.#terminating || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
 		const settled = Promise.withResolvers();
+		this.#writes.set(settled, void 0);
 		try {
-			stdin.write(`${text}\n`, (error) => {
-				settled.resolve(error === void 0 || error === null);
-			});
+			stdin.write(`${text}\n`, this.#confirmWrite.bind(this, settled));
 		} catch {
-			return Promise.resolve(false);
+			this.#settleWrite(settled, false);
+			return settled.promise;
+		}
+		if (this.#delivery > 0 && this.#writes.has(settled)) {
+			const timer = setTimeout(() => this.#settleWrite(settled, false), this.#delivery);
+			timer.unref();
+			this.#writes.set(settled, timer);
 		}
 		return settled.promise;
 	}
@@ -1069,7 +948,11 @@ var Process = class {
 			return;
 		}
 		const bytes = node_buffer.Buffer.byteLength(line) + 1;
-		if (!this.#requested && this.#pending + bytes > this.#backlog) return;
+		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();
@@ -1107,7 +990,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,
@@ -1119,14 +1002,66 @@ var Process = class {
 	#terminate() {
 		this.stop();
 	}
+	#removeAbortListener() {
+		if (this.#signal === void 0 || this.#abort === void 0) return;
+		this.#signal.removeEventListener("abort", this.#abort);
+	}
+	#confirmWrite(settled, error) {
+		if (error === void 0 || error === null) {
+			this.#settleWrite(settled, true);
+			return;
+		}
+		this.#failInputCallback(error);
+	}
+	#completeInput() {
+		this.#input -= 1;
+	}
+	#settleWrite(settled, accepted) {
+		if (!this.#writes.has(settled)) return;
+		const timer = this.#writes.get(settled);
+		this.#writes.delete(settled);
+		clearTimeout(timer);
+		settled.resolve(accepted);
+	}
+	#settleWrites() {
+		for (const settled of this.#writes.keys()) this.#settleWrite(settled, false);
+	}
+	#failInputStream(cause) {
+		if (this.#child.stdin.writableEnded || this.#input > 0) {
+			this.#settleWrites();
+			return;
+		}
+		this.#failInputCallback(cause);
+	}
+	#failInputCallback(cause) {
+		if (this.#failure !== void 0 || this.#terminating) return;
+		this.#failure = cause;
+		this.#settleWrites();
+		this.#emitter.emit("error", new _src_core.ProcessError("The standard-input channel failed", {
+			code: "protocol",
+			cause
+		}));
+	}
+	#capBacklog() {
+		const limit = this.#backlog * 2;
+		while (this.#pending > limit && this.#queue.length > this.#head) {
+			const line = this.#queue.pop();
+			if (line === void 0) break;
+			this.#pending -= node_buffer.Buffer.byteLength(line) + 1;
+			this.#truncated = true;
+		}
+	}
 	async #kill() {
 		this.#terminating = true;
+		this.#capBacklog();
 		this.#relieve();
 		const confirmed = await stopChild(this.#child, this.#grace, _src_core.PROCESS_CONFIRMATION);
+		this.#settleWrites();
 		this.#child.stdin.destroy();
 		return confirmed;
 	}
 	async #teardown() {
+		this.#removeAbortListener();
 		await this.stop();
 		this.#emitter.destroy();
 	}
@@ -1214,8 +1149,9 @@ var ProcessManager = class {
 	* 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.
+	* 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
@@ -1329,25 +1265,366 @@ function createProcessManager(options) {
 	return new ProcessManager(options);
 }
 //#endregion
+//#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 (!node_buffer.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 : node_buffer.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`. A host fault while writing that input terminates the run by design and
+* marks its result failed; a strict rejection carries the host fault as its cause. This differs
+* from `Process` constructor input, whose package-initiated input phase stays quiet. Unless `strict`
+* is `false`, a failed run rejects with a {@link ProcessError} carrying the {@link ExecuteResult};
+* {@link createExecuteError} constructs every rejection outside the input-fault door. 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 ?? _src_core.PROCESS_OUTPUT;
+	const grace = optionGrace ?? _src_core.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 inputFailure = 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 = (0, node_child_process.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: node_buffer.Buffer.concat(outChunks),
+			stderr: node_buffer.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, _src_core.PROCESS_CONFIRMATION).then(() => {
+			if (finish.signal.aborted) return;
+			confirmTimer = setTimeout(() => finish.abort(), _src_core.PROCESS_CONFIRMATION);
+		});
+	}, { once: true });
+	inputFailure.signal.addEventListener("abort", () => {
+		if (finish.signal.aborted) return;
+		cause = inputFailure.signal.reason;
+		terminate.abort();
+	}, { once: true });
+	child.stdin.on("error", (error) => inputFailure.abort(error));
+	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, (error) => {
+		if (error !== void 0 && error !== null) inputFailure.abort(error);
+	});
+	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) {
+		if (cause !== void 0 && cause === inputFailure.signal.reason) throw new _src_core.ProcessError(`Command '${result.command}' failed while writing standard input`, {
+			code: "input",
+			context: {
+				command: result.command,
+				code: result.code,
+				signal: result.signal
+			},
+			cause: inputFailure.signal.reason,
+			result
+		});
+		throw (0, _src_core.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 ?? _src_core.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 = (0, node_child_process.spawnSync)(plan.file, [...plan.arguments], {
+		cwd: workspace,
+		env: environment,
+		encoding: "buffer",
+		maxBuffer: limit,
+		killSignal: "SIGKILL",
+		windowsHide: true,
+		windowsVerbatimArguments: plan.verbatim,
+		...text !== void 0 ? { input: node_buffer.Buffer.from(text) } : {},
+		...timeout > 0 ? { timeout } : {}
+	});
+	const error = outcome.error;
+	const fault = error !== void 0 && "code" in error && (0, _orkestrel_contract.isString)(error.code) ? error.code : "";
+	const result = buildExecuteResult({
+		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.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 = (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
 exports.Process = Process;
 exports.ProcessManager = ProcessManager;
-exports.buildRunResult = buildRunResult;
+exports.Retention = Retention;
+exports.buildExecutableCandidates = buildExecutableCandidates;
+exports.buildExecuteResult = buildExecuteResult;
+exports.buildPlatformSpawn = buildPlatformSpawn;
 exports.buildSpawn = buildSpawn;
 exports.createProcess = createProcess;
 exports.createProcessManager = createProcessManager;
 exports.detach = detach;
+exports.execute = execute;
+exports.executeSync = executeSync;
 exports.formatCommand = formatCommand;
 exports.isExited = isExited;
 exports.isFile = isFile;
 exports.killProcess = killProcess;
 exports.killTree = killTree;
 exports.mergeEnvironment = mergeEnvironment;
+exports.mergePlatformEnvironment = mergePlatformEnvironment;
 exports.quoteArgument = quoteArgument;
+exports.readPlatformVariable = readPlatformVariable;
 exports.readVariable = readVariable;
 exports.resolveExecutable = resolveExecutable;
-exports.retainChunk = retainChunk;
-exports.run = run;
-exports.runSync = runSync;
+exports.snapshotCommand = snapshotCommand;
 exports.stopChild = stopChild;
 exports.trimHead = trimHead;
 exports.trimTail = trimTail;