@orkestrel/process 0.0.15 → 0.0.16

package/dist/src/server/index.cjs

@@ -9,7 +9,7 @@ let _src_core = require("../core/index.cjs");
 let node_readline = require("node:readline");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let node_string_decoder = require("node:string_decoder");
-//#region src/server/cloners.ts
+// src/server/cloners.ts
 /**
 * Takes one owned frozen snapshot of a caller's command.
 *
@@ -44,8 +44,7 @@ function snapshotCommand(command) {
 		...isolated === void 0 ? {} : { isolated }
 	});
 }
-//#endregion
-//#region src/server/helpers.ts
+// src/server/helpers.ts
 /**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
 *
@@ -66,13 +65,13 @@ function snapshotCommand(command) {
 function trimTail(bytes, limit) {
 	const buffer = node_buffer.Buffer.isBuffer(bytes) ? bytes : node_buffer.Buffer.from(bytes);
 	if (buffer.byteLength <= limit) return buffer;
-	let start = buffer.byteLength - limit;
-	while (start < buffer.byteLength) {
+	const offset = buffer.byteLength - limit;
+	if (!(offset < buffer.byteLength)) return node_buffer.Buffer.from(buffer.subarray(offset));
+	for (const start of Array.from({ length: Math.ceil(buffer.byteLength - offset) }, (_, index) => offset + index)) {
 		const byte = buffer[start];
-		if (byte === void 0 || (byte & 192) !== 128) break;
-		start += 1;
+		if (byte === void 0 || (byte & 192) !== 128) return node_buffer.Buffer.from(buffer.subarray(start));
 	}
-	return node_buffer.Buffer.from(buffer.subarray(start));
+	return node_buffer.Buffer.from(buffer.subarray(buffer.byteLength));
 }
 /**
 * Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
@@ -100,18 +99,12 @@ function trimHead(bytes, limit) {
 	const excluded = buffer[limit];
 	if (excluded === void 0 || (excluded & 192) !== 128) return node_buffer.Buffer.from(buffer.subarray(0, limit));
 	const floor = Math.max(0, limit - 3);
-	let start = limit - 1;
-	while (start >= floor) {
+	for (const start of Array.from({ length: Math.max(0, Math.floor(limit - floor)) }, (_, index) => limit - 1 - index)) {
 		const lead = buffer[start];
 		if (lead !== void 0 && (lead & 192) !== 128) {
-			let span = 1;
-			if ((lead & 224) === 192) span = 2;
-			else if ((lead & 240) === 224) span = 3;
-			else if ((lead & 248) === 240) span = 4;
-			if (start + span > limit) return node_buffer.Buffer.from(buffer.subarray(0, start));
+			if (start + ((lead & 224) === 192 ? 2 : (lead & 240) === 224 ? 3 : (lead & 248) === 240 ? 4 : 1) > limit) return node_buffer.Buffer.from(buffer.subarray(0, start));
 			break;
 		}
-		start -= 1;
 	}
 	return node_buffer.Buffer.from(buffer.subarray(0, limit));
 }
@@ -553,6 +546,27 @@ function isExited(child) {
 	return child.exitCode !== null || child.signalCode !== null;
 }
 /**
+* Reports whether a process or POSIX process group still exists.
+*
+* @param pid - A positive process id, or a negative POSIX process-group id
+* @returns True when the host confirms existence or refuses permission; false for ESRCH; undefined for another host failure
+* @throws A {@link ProcessError} coded `invalid` for an unsafe integer, zero, minus one, or a negative id on Windows
+* @remarks Negative ids probe POSIX process groups. The `process.platform` branch refuses negative ids on Windows, where the host supports positive process ids only.
+* @example
+* ```ts
+* inspectProcess(process.pid) // true
+* ```
+*/
+function inspectProcess(pid) {
+	if (!Number.isSafeInteger(pid) || pid === 0 || pid === -1 || process.platform === "win32" && pid < 0) throw (0, _src_core.createInvalidError)("process id", pid);
+	try {
+		return process.kill(pid, 0);
+	} catch (error) {
+		const code = (0, _orkestrel_contract.isError)(error) && "code" in error ? error.code : void 0;
+		return code === "ESRCH" ? false : code === "EPERM" ? true : void 0;
+	}
+}
+/**
 * Signals one owned child process, or its detached process group on a POSIX host.
 *
 * @remarks
@@ -745,262 +759,6 @@ function buildExecuteResult(input) {
 	});
 }
 /**
-* 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. Each capture keeps one byte beyond `limit`, so the single
-* code-point-boundary trim in {@link buildExecuteResult} reads the first excluded byte and never
-* delivers a split multibyte sequence. A positive `timeout` and an aborting `signal` both terminate the
-* child through the same bounded stop, and only the earliest is recorded: a timeout reports
-* `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
-* a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
-* 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 = [];
-	let spawned = false;
-	let expired = false;
-	let aborted = false;
-	let outRetained = 0;
-	let errRetained = 0;
-	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: outRetained > limit || errRetained > limit,
-			limit,
-			...cause === void 0 ? {} : { cause }
-		}));
-	}, { once: true });
-	terminate.signal.addEventListener("abort", () => {
-		if (finish.signal.aborted) return;
-		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 captured = captureChunk(chunk, limit + 1 - outRetained);
-		if (captured === void 0) return;
-		outRetained += captured.byteLength;
-		outChunks.push(captured);
-	});
-	child.stderr.on("data", (chunk) => {
-		const captured = captureChunk(chunk, limit + 1 - errRetained);
-		if (captured === void 0) return;
-		errRetained += captured.byteLength;
-		errChunks.push(captured);
-	});
-	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;
-}
-/**
-* 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;
-}
-/**
 * Spawns one command as a detached process and returns without waiting for it.
 *
 * @remarks
@@ -1041,8 +799,7 @@ function detach(command, options) {
 	child.once("error", () => void 0);
 	child.unref();
 }
-//#endregion
-//#region src/server/processes/Supervisor.ts
+// src/server/processes/Supervisor.ts
 /**
 * Supervises one child process and reports each lifecycle moment to the face composing it.
 *
@@ -1055,7 +812,7 @@ function detach(command, options) {
 * emitter and event map its consumers subscribe to.
 *
 * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read the
-* host child directly, so they expose native exit as soon as the host records it, and `ending`
+* host child directly, so they expose native exit as soon as the host records it, and `ended`
 * settles at that same moment. `settled`, `exit`, and `evidence` reach one terminal moment after the
 * read channels close or the bounded `drain` window cuts them off. That window is armed by the
 * child's native exit and by a termination this package initiated, so every way a child can end
@@ -1105,12 +862,12 @@ var Supervisor = class {
 	#delivery;
 	#decoder = new node_string_decoder.StringDecoder("utf8");
 	#exit = Promise.withResolvers();
-	#ending = Promise.withResolvers();
+	#ended = Promise.withResolvers();
 	#signal;
 	#abort;
 	#writes = /* @__PURE__ */ new Map();
 	#tail = node_buffer.Buffer.alloc(0);
-	#stopping = false;
+	#terminated = false;
 	#settled = false;
 	#input = 0;
 	#failure;
@@ -1221,8 +978,8 @@ var Supervisor = class {
 		return this.#settled;
 	}
 	/** Reports whether termination began, including after the terminal moment. */
-	get stopping() {
-		return this.#stopping;
+	get terminated() {
+		return this.#terminated;
 	}
 	/**
 	* Settles at the child's own ending, awaited without the terminal moment's drain window.
@@ -1232,8 +989,8 @@ var Supervisor = class {
 	* the host records them. It settles at the native exit, and at the terminal moment for a child
 	* whose spawn produced no native exit at all, so it can never outlive the supervision.
 	*/
-	get ending() {
-		return this.#ending.promise;
+	get ended() {
+		return this.#ended.promise;
 	}
 	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
@@ -1279,7 +1036,7 @@ var Supervisor = class {
 	*/
 	deliver(bytes) {
 		const stdin = this.#child.stdin;
-		if (this.#settled || this.#stopping || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
+		if (this.#settled || this.#terminated || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
 		const settled = Promise.withResolvers();
 		this.#writes.set(settled, void 0);
 		try {
@@ -1299,7 +1056,7 @@ var Supervisor = class {
 	* Closes the standard-input channel while leaving the child running.
 	*
 	* @remarks
-	* Never rejects, and terminates nothing: no signal is sent, `stopping` stays false, no drain
+	* Never rejects, and terminates nothing: no signal is sent, `terminated` stays false, no drain
 	* window is armed, and the terminal moment does not arrive. The child observes end of input and
 	* decides for itself what to do about it, which is what separates this from `stop`.
 	*
@@ -1357,7 +1114,7 @@ var Supervisor = class {
 		this.#settle(true);
 	}
 	#expire() {
-		this.#ending.resolve();
+		this.#ended.resolve();
 		if (this.#settled) return;
 		this.#wait();
 	}
@@ -1379,7 +1136,7 @@ var Supervisor = class {
 			drained
 		});
 		this.#exit.resolve(exit);
-		this.#ending.resolve();
+		this.#ended.resolve();
 		this.#terminal(exit);
 		this.#child.stdout.destroy();
 		this.#child.stderr.destroy();
@@ -1403,7 +1160,7 @@ var Supervisor = class {
 	}
 	#endInput() {
 		const stdin = this.#child.stdin;
-		if (this.#stopping || this.#settled || stdin.writableEnded || stdin.destroyed) return Promise.resolve();
+		if (this.#terminated || this.#settled || stdin.writableEnded || stdin.destroyed) return Promise.resolve();
 		const ended = Promise.withResolvers();
 		stdin.end(() => ended.resolve());
 		return ended.promise;
@@ -1430,7 +1187,7 @@ var Supervisor = class {
 			this.#settleWrites();
 			return;
 		}
-		if (this.#failure !== void 0 || this.#stopping) return;
+		if (this.#failure !== void 0 || this.#terminated) return;
 		this.#failure = cause;
 		this.#settleWrites();
 		this.#fault(new _src_core.ProcessError("The standard-input channel failed", {
@@ -1439,7 +1196,7 @@ var Supervisor = class {
 		}));
 	}
 	async #kill() {
-		this.#stopping = true;
+		this.#terminated = true;
 		this.#relieve?.();
 		const confirmed = await stopChild(this.#child, this.#grace, _src_core.PROCESS_CONFIRMATION);
 		this.#settleWrites();
@@ -1453,8 +1210,7 @@ var Supervisor = class {
 		this.#teardown();
 	}
 };
-//#endregion
-//#region src/server/processes/Process.ts
+// src/server/processes/Process.ts
 /**
 * Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
 * every observation channel aligned at termination.
@@ -1590,8 +1346,8 @@ var Process = class {
 		return this.#engine.settled;
 	}
 	/** Reports whether termination began, including after the terminal moment. */
-	get stopping() {
-		return this.#engine.stopping;
+	get terminated() {
+		return this.#engine.terminated;
 	}
 	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
@@ -1685,9 +1441,9 @@ var Process = class {
 			return;
 		}
 		const bytes = node_buffer.Buffer.byteLength(line) + 1;
-		const stopping = this.#engine.stopping;
-		const limit = stopping ? this.#backlog * 2 : this.#backlog;
-		if ((!this.#requested || stopping) && this.#pending + bytes > limit) {
+		const terminated = this.#engine.terminated;
+		const limit = terminated ? this.#backlog * 2 : this.#backlog;
+		if ((!this.#requested || terminated) && this.#pending + bytes > limit) {
 			this.#truncated = true;
 			return;
 		}
@@ -1696,14 +1452,14 @@ var Process = class {
 		this.#restrain();
 	}
 	#restrain() {
-		if (this.#paused || this.#engine.stopping || !this.#requested) return;
+		if (this.#paused || this.#engine.terminated || !this.#requested) return;
 		if (this.#pending < this.#backlog) return;
 		this.#paused = true;
 		this.#reader.pause();
 	}
 	#relieve() {
 		if (!this.#paused || this.#ended) return;
-		if (!this.#engine.stopping && this.#pending > this.#backlog / 2) return;
+		if (!this.#engine.terminated && this.#pending > this.#backlog / 2) return;
 		this.#paused = false;
 		this.#reader.resume();
 	}
@@ -1743,8 +1499,7 @@ var Process = class {
 		}
 	}
 };
-//#endregion
-//#region src/server/processes/ProcessManager.ts
+// src/server/processes/ProcessManager.ts
 /**
 * Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
 * every live child on teardown.
@@ -1781,7 +1536,7 @@ var ProcessManager = class {
 	#ids = /* @__PURE__ */ new Set();
 	#orphans = /* @__PURE__ */ new Set();
 	#destroying = false;
-	#ending;
+	#ended;
 	/**
 	* Constructs a process registry.
 	*
@@ -1869,10 +1624,10 @@ var ProcessManager = class {
 	* @returns The stable barrier shared by every call
 	*/
 	destroy() {
-		if (this.#ending !== void 0) return this.#ending;
+		if (this.#ended !== void 0) return this.#ended;
 		this.#destroying = true;
-		this.#ending = this.#teardown();
-		return this.#ending;
+		this.#ended = this.#teardown();
+		return this.#ended;
 	}
 	#construct(id, options) {
 		try {
@@ -1911,8 +1666,7 @@ var ProcessManager = class {
 		this.#emitter.destroy();
 	}
 };
-//#endregion
-//#region src/server/processes/Session.ts
+// src/server/processes/Session.ts
 /**
 * Supervises one child and publishes its standard output as raw bytes.
 *
@@ -1930,7 +1684,7 @@ var ProcessManager = class {
 *
 * The standard-input channel is open from the spawn, and `end` closes it without terminating
 * anything. That is the member a cooperative protocol reaches for: the child observes end of input
-* and exits on its own, which `ending` reports. `stop` and `destroy` remain the terminations, and
+* and exits on its own, which `ended` reports. `stop` and `destroy` remain the terminations, and
 * `exit` remains the terminal moment — the native exit plus at most `drain` while a descendant holds
 * the inherited read ends.
 *
@@ -2012,12 +1766,12 @@ var Session = class {
 		return this.#engine.settled;
 	}
 	/** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
-	get stopping() {
-		return this.#engine.stopping;
+	get terminated() {
+		return this.#engine.terminated;
 	}
 	/** Settles at the child's own ending, awaited without the terminal moment's drain window. */
-	get ending() {
-		return this.#engine.ending;
+	get ended() {
+		return this.#engine.ended;
 	}
 	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
@@ -2042,7 +1796,7 @@ var Session = class {
 	* Closes the standard-input channel and leaves the child running.
 	*
 	* @remarks
-	* Never rejects and terminates nothing: `stopping` stays false and the terminal moment does not
+	* Never rejects and terminates nothing: `terminated` stays false and the terminal moment does not
 	* arrive. Every call shares one barrier, which resolves after the host flushes the writes it had
 	* already accepted. A later `write` resolves `false`.
 	*
@@ -2090,8 +1844,7 @@ var Session = class {
 		this.#engine.stdout.off("data", this.#output);
 	}
 };
-//#endregion
-//#region src/server/factories.ts
+// src/server/factories.ts
 /**
 * Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
 * holds the published contract rather than the `Process` class.
@@ -2160,7 +1913,284 @@ function createSession(options) {
 function createProcessManager(options) {
 	return new ProcessManager(options);
 }
-//#endregion
+// src/server/processes/Execution.ts
+/** Owns the child, capture, cancellation, and terminal state of one buffered execution. */
+var Execution = class {
+	#child;
+	#settled;
+	#terminate;
+	#cleanup;
+	#finish;
+	#inputFailure;
+	#outChunks = [];
+	#errChunks = [];
+	#strict;
+	#spawned = false;
+	#expired = false;
+	#aborted = false;
+	#outRetained = 0;
+	#errRetained = 0;
+	#cause;
+	#timeoutTimer;
+	#confirmTimer;
+	constructor(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;
+		this.#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
+		});
+		this.#settled = Promise.withResolvers();
+		this.#terminate = new AbortController();
+		this.#cleanup = new AbortController();
+		this.#finish = new AbortController();
+		this.#inputFailure = new AbortController();
+		this.#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
+		});
+		this.#finish.signal.addEventListener("abort", () => {
+			clearTimeout(this.#timeoutTimer);
+			clearTimeout(this.#confirmTimer);
+			this.#cleanup.abort();
+			this.#settled.resolve(buildExecuteResult({
+				command: line,
+				stdout: node_buffer.Buffer.concat(this.#outChunks),
+				stderr: node_buffer.Buffer.concat(this.#errChunks),
+				code: this.#child.exitCode,
+				signal: this.#child.signalCode,
+				expired: this.#expired,
+				aborted: this.#aborted,
+				truncated: this.#outRetained > limit || this.#errRetained > limit,
+				limit,
+				...this.#cause === void 0 ? {} : { cause: this.#cause }
+			}));
+		}, { once: true });
+		this.#terminate.signal.addEventListener("abort", () => {
+			if (this.#finish.signal.aborted) return;
+			clearTimeout(this.#timeoutTimer);
+			this.#cleanup.abort();
+			stopChild(this.#child, grace, _src_core.PROCESS_CONFIRMATION).then(() => {
+				if (this.#finish.signal.aborted) return;
+				this.#confirmTimer = setTimeout(() => this.#finish.abort(), _src_core.PROCESS_CONFIRMATION);
+			});
+		}, { once: true });
+		this.#inputFailure.signal.addEventListener("abort", () => {
+			if (this.#finish.signal.aborted) return;
+			this.#cause = this.#inputFailure.signal.reason;
+			this.#terminate.abort();
+		}, { once: true });
+		this.#child.stdin.on("error", (error) => this.#inputFailure.abort(error));
+		this.#child.stdout.on("data", (chunk) => {
+			const captured = captureChunk(chunk, limit + 1 - this.#outRetained);
+			if (captured === void 0) return;
+			this.#outRetained += captured.byteLength;
+			this.#outChunks.push(captured);
+		});
+		this.#child.stderr.on("data", (chunk) => {
+			const captured = captureChunk(chunk, limit + 1 - this.#errRetained);
+			if (captured === void 0) return;
+			this.#errRetained += captured.byteLength;
+			this.#errChunks.push(captured);
+		});
+		this.#child.once("spawn", () => {
+			this.#spawned = true;
+		});
+		this.#child.once("error", (error) => {
+			if (this.#spawned) return;
+			this.#cause = error;
+			this.#finish.abort();
+		});
+		this.#child.once("close", () => this.#finish.abort());
+		if (text !== void 0) this.#child.stdin.write(text, (error) => {
+			if (error !== void 0 && error !== null) this.#inputFailure.abort(error);
+		});
+		this.#child.stdin.end();
+		if (timeout > 0) this.#timeoutTimer = setTimeout(() => {
+			this.#expired = true;
+			this.#terminate.abort();
+		}, timeout);
+		if (optionSignal !== void 0) {
+			optionSignal.addEventListener("abort", () => {
+				this.#aborted = true;
+				this.#terminate.abort();
+			}, {
+				once: true,
+				signal: this.#cleanup.signal
+			});
+			if (optionSignal.aborted) {
+				this.#aborted = true;
+				this.#terminate.abort();
+			}
+		}
+	}
+	get settled() {
+		return this.#settled.promise;
+	}
+	read(result) {
+		if (result.failed && this.#strict) {
+			if (this.#cause !== void 0 && this.#cause === this.#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: this.#inputFailure.signal.reason,
+				result
+			});
+			throw (0, _src_core.createExecuteError)(result, this.#cause);
+		}
+		return result;
+	}
+};
+// 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. Each capture keeps one byte beyond `limit`, so the single
+* code-point-boundary trim in {@link buildExecuteResult} reads the first excluded byte and never
+* delivers a split multibyte sequence. A positive `timeout` and an aborting `signal` both terminate the
+* child through the same bounded stop, and only the earliest is recorded: a timeout reports
+* `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
+* a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
+* 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 execution = new Execution(command, options);
+	const result = await execution.settled;
+	return execution.read(result);
+}
+// 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;
+}
 exports.Process = Process;
 exports.ProcessManager = ProcessManager;
 exports.Session = Session;
@@ -2177,6 +2207,7 @@ exports.detach = detach;
 exports.execute = execute;
 exports.executeSync = executeSync;
 exports.formatCommand = formatCommand;
+exports.inspectProcess = inspectProcess;
 exports.isExited = isExited;
 exports.isFile = isFile;
 exports.killProcess = killProcess;