@j-o-r/sh 1.1.31 → 1.2.0

package/lib/SHExecute.js

@@ -1,58 +1,16 @@
 import { spawnSync, spawn } from 'node:child_process';
+import { DEFAULT_MAX_BUFFER, parseDuration } from './internal.js';
 
 /**
- * Validates if a number is a finite positive integer (including 0).
- *
- * @param {unknown} n - Value to check.
- * @returns {boolean} True if finite non-negative integer.
- */
-const isFinitePosInt = (n) => Number.isFinite(n) && n >= 0;
-
-/**
- * Parses a human-readable duration into milliseconds.
- *
- * Supports: numbers (ms), '250ms', '2s'. null/undefined → 0; invalid → throws.
- *
- * @param {number|string|null|undefined} d - Duration input.
- * @returns {number} ms.
- * @throws {Error} Invalid format/type.
- */
-const parseDuration = (d) => {
-  if (typeof d === 'number') return isFinitePosInt(d) ? d : (() => { throw new Error('Invalid duration'); })();
-  if (typeof d === 'string') {
-    const m = d.match(/^(\d+)(ms|s)?$/);
-    if (!m) throw new Error('Invalid duration string');
-    const n = Number(m[1]);
-    return m[2] === 's' ? n * 1000 : n;
-  }
-  if (d == null) return 0;
-  throw new Error('Invalid duration type');
-};
-
-/**
- * Retrieves child PIDs of a given parent PID using pgrep -P.
- *
- * @param {number} pid - Parent PID.
- * @returns {Promise<number[]>} Array of child PIDs.
+ * Grace period (ms) before escalating SIGTERM → SIGKILL for a process group
+ * that is still alive after a graceful SIGTERM (i.e. it trapped/ignored it).
  */
-const childrenOf = (pid) => new Promise((resolve, reject) => {
-  const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
-  const out = [];
-  p.stdout.on('data', (chunk) => out.push(chunk));
-  p.on('close', (code) => {
-    if (code === 0) {
-      const ids = Buffer.concat(out).toString('utf8').trim().split(/\s+/).map(Number).filter(Boolean);
-      resolve(ids);
-    } else if (code === 1) {
-      resolve([]); // no children or error
-    }
-  });
-  p.on('error', reject);
-});
+const ESCALATION_GRACE_MS = 1000;
 
 /**
- * @typedef {import('../SH.js').SHOptions & { maxBuffer?: number }} SHExecuteOptions
- * @description Extended options for SHExecute: adds `maxBuffer` (bytes per stream, default 1MB).
+ * @typedef {import('./SHDispatch.js').SHOptions} SHExecuteOptions
+ * @description Options accepted by SHExecute — the shared SHOptions; `maxBuffer`
+ * (bytes per stream) defaults to 512000 (500 KiB).
  */
 
 /**
@@ -63,214 +21,321 @@ const childrenOf = (pid) => new Promise((resolve, reject) => {
  * Key features:
  * - **Shell mode**: If `options.shell` is string/true, runs `${prefix}; ${command}` via shell ('bash' default).
  * - **No-shell mode**: Uses `/usr/bin/env -S ${command}` for direct exec (ignores prefix).
- * - **Rolling timeout**: `options.timeout` (ms/'2s'); resets on stdout/stderr data. SIGTERM on expiry.
- * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (1MB default); appends truncation markers.
+ * - **Timeouts**: `options.timeout` (ms/'2s') is an absolute wall-clock timeout —
+ *   the process is killed after the full duration regardless of output, in both
+ *   `run()` and `runSync()`. It is stripped from the spawn options so Node's
+ *   native absolute spawn timeout never interferes with the custom timer (which
+ *   reports a clear `Process timed out after <N>ms.` error and tears down the
+ *   whole process group via `kill()`). `runSync()` passes it to `spawnSync`, whose
+ *   native semantics are the same (absolute).
+ * - **Process-group teardown**: The child is always spawned as a new process-group
+ *   leader (`detached: true` in the spawn options, independent of the public
+ *   `detached` option). `kill()` sends the signal to the whole group via a
+ *   negative PID, tearing down the entire tree (children, grandchildren, …) in
+ *   one shot — no `pgrep` discovery needed. A graceful SIGTERM is escalated to
+ *   SIGKILL after {@link ESCALATION_GRACE_MS} for processes that ignore SIGTERM.
+ * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (512000 bytes / 500 KiB default); appends truncation markers.
  * - **Payload**: `run(payload)` writes string to stdin (forces pipe).
- * - **Detached**: If `options.detached`, resolves early (~1s) and unrefs.
- * - **Kill**: Terminates process + children via pgrep.
+ * - **Detached**: If the public `options.detached` is set, resolves early (~1s)
+ *   and unrefs. Unless the caller explicitly set `stdio`, SHDispatch forces
+ *   `stdio: 'ignore'` for detached runs, because open pipes keep the parent's
+ *   event loop alive and defeat detachment.
+ * - **Kill**: Terminates the whole process group (negative-PID kill) and
+ *   escalates SIGTERM → SIGKILL after a grace period.
  *
  * @example
  * const exec = new SHExecute('ls', 'set -euo pipefail', { timeout: '5s' });
  * const out = await exec.run();
  */
 class SHExecute {
-  #forcedKill = false;
-  /** @type {import('child_process').ChildProcess | null} */
-  #proc = null;
-  #prefix = '';
-  #command = '';
-  /** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
-  #options = {};
-  #stdoutChunks = [];
-  #stderrChunks = [];
-  #stdoutLen = 0;
-  #stderrLen = 0;
-  #maxBuffer = 500 * 1024; // 500KB per stream
-  #truncated = { stdout: false, stderr: false };
-  #timedOut = false;
+	#forcedKill = false;
+	/** @type {import('child_process').ChildProcess | null} */
+	#proc = null;
+	#prefix = '';
+	#command = '';
+	/** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
+	#options = {};
+	#stdoutChunks = [];
+	#stderrChunks = [];
+	#stdoutLen = 0;
+	#stderrLen = 0;
+	#maxBuffer = DEFAULT_MAX_BUFFER; // 512000 bytes (500 KiB) per stream
+	#truncated = { stdout: false, stderr: false };
+	#timedOut = false;
+	/** Absolute wall-clock timeout in ms; 0 disables. Never resets on output. */
+	#timeout = 0;
+	/** Pending SIGTERM→SIGKILL escalation timer (set by `kill('SIGTERM')`). */
+	#escalationTimer = null;
+
+	/**
+	 * @param {string} command - Command to execute.
+	 * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
+	 * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
+	 */
+	constructor(command, prefix, options = {}) {
+		this.#prefix = prefix;
+		this.#command = command;
+		// maxBuffer and timeout are SH-level options, not spawn options.
+		// timeout in particular must not reach spawn(): since Node 15.5 it triggers a
+		// native absolute timeout that would defeat the custom timer in run().
+		const { maxBuffer, timeout, ...spawnOpts } = options ?? {};
+		this.#maxBuffer = Number.isFinite(maxBuffer) && maxBuffer > 0 ? maxBuffer : this.#maxBuffer;
+		this.#timeout = parseDuration(timeout ?? 0);
+		this.#options = spawnOpts;
+	}
+
+	/**
+	 * Synchronous execution.
+	 *
+	 * Process-group teardown does not apply here: `spawnSync` blocks until the
+	 * process exits or its native absolute `timeout` fires, so there is no async
+	 * kill to escalate. Grandchildren may survive a `spawnSync` timeout.
+	 *
+	 * @param {string} [payload] - Stdin data (forces pipe).
+	 * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+	 * @throws {Error} Invalid payload type.
+	 */
+	runSync(payload) {
+		this.#forcedKill = false;
+		if (payload && typeof payload !== 'string') {
+			throw new Error('Argument is not a string');
+		}
+		/** @type {import('node:child_process').SpawnSyncOptions} */
+		const options = { ...this.#options, shell: false };
+		// spawnSync supports timeout natively; semantics are absolute (no rolling
+		// reset), matching the async run().
+		if (this.#timeout > 0) {
+			options.timeout = this.#timeout;
+		}
+		if (payload) {
+			const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
+			stdio[0] = 'pipe';
+			// @ts-ignore — stdio widens to string[] via the ['pipe', 'pipe', 'pipe'] literal; runtime values are valid StdioOptions.
+			options.stdio = stdio;
+			options.input = payload;
+		}
+
+		const shellOpt = this.#options?.shell;
+		if (shellOpt) {
+			const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+			const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
+			return spawnSync(sh, ['-c', cmd], options);
+		}
+		// no-shell mode
+		return spawnSync('/usr/bin/env', ['-S', this.#command], options);
+	}
+
+	/**
+	 * Asynchronous execution with buffering/timeout/kill.
+	 *
+	 * Resolves stdout (trimmed) on success.
+	 *
+	 * @param {string} [payload] - Stdin data (forces pipe).
+	 * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
+	 *   Rejects with an Error on command failure (message includes the exit code,
+	 *   or the signal name for signal kills, plus any already-received stdout and
+	 *   stderr), timeout expiry, or forced kill. On timeout/forced-kill the
+	 *   already-received stdout/stderr is preserved in the error message.
+	 */
+	run(payload) {
+		this.#forcedKill = false;
+		if (payload && typeof payload !== 'string') {
+			throw new Error('Argument is not a string');
+		}
+		// The public `detached` option only controls the early-resolve (~1s)
+		// behavior below. The spawn flag is always forced to `detached: true` so
+		// the child becomes a new process-group leader and the whole tree can be
+		// torn down via a negative-PID kill.
+		const publicDetached = this.#options.detached;
+		/** @type {import('child_process').SpawnOptions} */
+		const options = { ...this.#options, shell: false, detached: true };
+		if (payload) {
+			const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
+			stdio[0] = 'pipe';
+			// @ts-ignore — stdio widens to string[] via the ['pipe', 'pipe', 'pipe'] literal; runtime values are valid StdioOptions.
+			options.stdio = stdio;
+		}
 
-  /**
-   * @param {string} command - Command to execute.
-   * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
-   * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
-   */
-  constructor(command, prefix, options = {}) {
-    this.#prefix = prefix;
-    this.#command = command;
-    const { maxBuffer, ...spawnOpts } = options ?? {};
-    this.#maxBuffer = Number.isFinite(maxBuffer) && maxBuffer > 0 ? maxBuffer : this.#maxBuffer;
-    this.#options = spawnOpts;
-  }
+		// reset buffers for each run
+		this.#stdoutChunks = [];
+		this.#stderrChunks = [];
+		this.#stdoutLen = 0;
+		this.#stderrLen = 0;
+		this.#truncated = { stdout: false, stderr: false };
+		this.#timedOut = false;
+		this.#escalationTimer = null;
 
-  /**
-   * Synchronous execution.
-   *
-   * @param {string} [payload] - Stdin data (forces pipe).
-   * @returns {import('child_process').SpawnSyncReturns<Buffer>}
-   * @throws {Error} Invalid payload type.
-   */
-  runSync(payload) {
-    this.#forcedKill = false;
-    if (payload && typeof payload !== 'string') {
-      throw new Error('Argument is not a string');
-    }
-    /** @type {import('node:child_process').SpawnSyncOptions} */
-    const options = { ...this.#options, shell: false };
-    if (payload) {
-      const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
-      stdio[0] = 'pipe';
-      // @ts-ignore
-      options.stdio = stdio;
-      options.input = payload;
-    }
+		const shellOpt = this.#options?.shell;
+		if (shellOpt) {
+			const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+			const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
+			this.#proc = spawn(sh, ['-c', cmd], options);
+		} else {
+			this.#proc = spawn('/usr/bin/env', ['-S', this.#command], options);
+		}
 
-    const shellOpt = this.#options?.shell;
-    if (shellOpt) {
-      const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
-      const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
-      return spawnSync(sh, ['-c', cmd], options);
-    }
-    // no-shell mode
-    return spawnSync('/usr/bin/env', ['-S', this.#command], options);
-  }
+		if (payload) this.#proc.stdin?.end(payload);
 
-  /**
-   * Asynchronous execution with buffering/timeout/kill.
-   *
-   * Resolves stdout (trimmed) on success; rejects on error/timeout/kill.
-   *
-   * @param {string} [payload] - Stdin data (forces pipe).
-   * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
-   * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
-   */
-  run(payload) {
-    this.#forcedKill = false;
-    if (payload && typeof payload !== 'string') {
-      throw new Error('Argument is not a string');
-    }
-    /** @type {import('child_process').SpawnOptions} */
-    const options = { ...this.#options, shell: false };
-    if (payload) {
-      const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
-      stdio[0] = 'pipe';
-      // @ts-ignore
-      options.stdio = stdio;
-    }
+		const timeoutMs = this.#timeout;
+		let timeoutTimer = null;
+		/** @type {number} The timeout (ms) that actually fired, for the error message. */
+		let firedMs = 0;
 
-    // reset buffers for each run
-    this.#stdoutChunks = [];
-    this.#stderrChunks = [];
-    this.#stdoutLen = 0;
-    this.#stderrLen = 0;
-    this.#truncated = { stdout: false, stderr: false };
-    this.#timedOut = false;
+		const killOnTimeout = (ms) => {
+			firedMs = ms;
+			this.#timedOut = true;
+			this.kill('SIGTERM').catch(() => {});
+		};
 
-    const shellOpt = this.#options?.shell;
-    if (shellOpt) {
-      const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
-      const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
-      this.#proc = spawn(sh, ['-c', cmd], options);
-    } else {
-      this.#proc = spawn('/usr/bin/env', ['-S', this.#command], options);
-    }
+		// Timeout is absolute: never reset on output.
+		if (timeoutMs > 0) timeoutTimer = setTimeout(() => killOnTimeout(timeoutMs), timeoutMs);
 
-    if (payload) this.#proc.stdin?.end(payload);
+		this.#proc.stdout?.on('data', (chunk) => {
+			this.#stdoutLen += chunk.length;
+			// prevent TOKEN bombs
+			if (this.#stdoutLen <= this.#maxBuffer) {
+				this.#stdoutChunks.push(chunk);
+			} else {
+				this.#truncated.stdout = true;
+			}
+		});
 
-    const ms = parseDuration(this.#options?.timeout ?? 0);
-    let timeoutId = null;
-    const resetTimeout = () => {
-      if (timeoutId !== null) clearTimeout(timeoutId);
-      if (ms > 0) {
-        timeoutId = setTimeout(() => {
-          this.#timedOut = true;
-          this.kill('SIGTERM').catch(() => {});
-        }, ms);
-      }
-    };
+		this.#proc.stderr?.on('data', (chunk) => {
+			this.#stderrLen += chunk.length;
+			if (this.#stderrLen <= this.#maxBuffer) {
+				this.#stderrChunks.push(chunk);
+			} else {
+				this.#truncated.stderr = true;
+			}
+		});
 
-    if (ms > 0) resetTimeout();
+		return new Promise((resolve, reject) => {
+			if (publicDetached) {
+				setTimeout(() => {
+					if (timeoutTimer !== null) clearTimeout(timeoutTimer);
+					resolve('');
+					// #proc may already be null when kill() ran within the 1s window.
+					this.#proc?.unref();
+				}, 1000);
+			}
 
-    this.#proc.stdout?.on('data', (chunk) => {
-      this.#stdoutLen += chunk.length;
-      // prevent TOKEN bombs
-      if (this.#stdoutLen <= this.#maxBuffer) {
-        this.#stdoutChunks.push(chunk);
-      } else {
-        this.#truncated.stdout = true;
-      }
-      resetTimeout();
-    });
+			this.#proc.on('close', (code, signal) => {
+				if (timeoutTimer !== null) clearTimeout(timeoutTimer);
+				if (this.#escalationTimer !== null) {
+					clearTimeout(this.#escalationTimer);
+					this.#escalationTimer = null;
+				}
+				// Check timeout first: the timeout path kills with SIGTERM, which sets
+				// #forcedKill in the same tick; #forcedKill must not mask the timeout.
+				if (this.#timedOut) {
+					reject(new Error(this.#errorMessage(`Process timed out after ${firedMs}ms.`)));
+					return;
+				}
+				if (this.#forcedKill) {
+					reject(new Error(this.#errorMessage('Process killed (forced).')));
+					return;
+				}
+				if (code === 0) {
+					const stdoutBuf = this.#stdoutChunks.length ? Buffer.concat(this.#stdoutChunks) : Buffer.alloc(0);
+					let stdout = stdoutBuf.toString('utf8').trim();
+					if (this.#truncated.stdout) stdout += '\n[stdout truncated]\n';
+					resolve(stdout);
+				} else {
+					const reason = code === null ? `signal ${signal}` : `code ${code}`;
+					reject(new Error(this.#errorMessage(`Command failed with ${reason}.`)));
+				}
+			});
 
-    this.#proc.stderr?.on('data', (chunk) => {
-      this.#stderrLen += chunk.length;
-      if (this.#stderrLen <= this.#maxBuffer) {
-        this.#stderrChunks.push(chunk);
-      } else {
-        this.#truncated.stderr = true;
-      }
-      resetTimeout();
-    });
+			this.#proc.on('error', (err) => reject(err));
+		});
+	}
 
-    return new Promise((resolve, reject) => {
-      if (options.detached) {
-        setTimeout(() => {
-          if (timeoutId !== null) clearTimeout(timeoutId);
-          resolve('');
-          this.#proc.unref();
-        }, 1000);
-      }
+	/**
+	 * Terminates the whole process group (negative-PID kill).
+	 *
+	 * The child is spawned as a process-group leader, so a negative-PID kill
+	 * tears down the entire tree (children, grandchildren, …) in one shot — no
+	 * `pgrep` discovery required. A graceful SIGTERM is escalated to SIGKILL
+	 * after {@link ESCALATION_GRACE_MS} for processes that ignore SIGTERM.
+	 * Best-effort: an already-exited group (ESRCH) is treated as a no-op.
+	 *
+	 * @param {number | string} [signal='SIGTERM'] - Signal to send.
+	 * @returns {Promise<number[]>} Killed PIDs (the group-leader PID).
+	 * @throws {Error} No process/PID.
+	 */
+	async kill(signal = 'SIGTERM') {
+		if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
+		if (!this.#proc.pid) throw new Error('The process pid is undefined.');
+		this.#forcedKill = true;
+		const pid = this.#proc.pid;
+		const killed = [];
+		try {
+			// Negative PID = the whole process group.
+			try { process.kill(-pid, signal); killed.push(pid); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
+			// Escalate SIGTERM → SIGKILL after a grace period for processes that ignore SIGTERM.
+			if (signal === 'SIGTERM') {
+				this.#scheduleEscalation(pid);
+			}
+		} finally {
+			this.#proc = null;
+		}
+		return killed;
+	}
 
-      this.#proc.on('close', (code, signal) => {
-        if (timeoutId !== null) clearTimeout(timeoutId);
-        if (this.#forcedKill) {
-          reject(new Error('Process killed (forced).'));
-          return;
-        }
-        if (this.#timedOut) {
-          reject(new Error(`Process timed out after ${ms}ms.`));
-          return;
-        }
-        if (code === 0) {
-          const stdoutBuf = this.#stdoutChunks.length ? Buffer.concat(this.#stdoutChunks) : Buffer.alloc(0);
-          let stdout = stdoutBuf.toString('utf8').trim();
-          if (this.#truncated.stdout) stdout += '\n[stdout truncated]\n';
-          resolve(stdout);
-        } else {
-          const stderrBuf = this.#stderrChunks.length ? Buffer.concat(this.#stderrChunks) : Buffer.alloc(0);
-          let stderr = stderrBuf.toString('utf8');
-          if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
-          reject(new Error(`Command failed with code ${code}: ${stderr}`));
-        }
-      });
+	/**
+	 * Schedules a SIGKILL for the process group after {@link ESCALATION_GRACE_MS}
+	 * if it is still alive (i.e. it ignored the earlier SIGTERM).
+	 *
+	 * @private
+	 * @param {number} pid - Process-group leader PID.
+	 */
+	#scheduleEscalation(pid) {
+		this.#escalationTimer = setTimeout(() => {
+			this.#escalationTimer = null;
+			try {
+				// Signal 0 probes whether the group still exists (ESRCH = gone).
+				process.kill(-pid, 0);
+				// Still alive — it ignored SIGTERM; force-kill the whole group.
+				process.kill(-pid, 'SIGKILL');
+			} catch (e) {
+				// ESRCH: the group already died from SIGTERM — nothing to escalate.
+				// Other errors (e.g. EPERM) are best-effort; teardown stays non-fatal.
+			}
+		}, ESCALATION_GRACE_MS);
+	}
 
-      this.#proc.on('error', (err) => reject(err));
-    });
-  }
+	/**
+	 * Builds the already-received stdout/stderr (with truncation markers) as a
+	 * readable `[stdout]`/`[stderr]` block, so content received before a
+	 * timeout/kill/failure is preserved in the error message.
+	 *
+	 * @private
+	 * @returns {string} Formatted output block, or '' when nothing was received.
+	 */
+	#formatOutput() {
+		const parts = [];
+		const stdoutBuf = this.#stdoutChunks.length ? Buffer.concat(this.#stdoutChunks) : Buffer.alloc(0);
+		let stdout = stdoutBuf.toString('utf8');
+		if (this.#truncated.stdout) stdout += '\n[stdout truncated]\n';
+		if (stdout) parts.push(`[stdout]\n${stdout}`);
+		const stderrBuf = this.#stderrChunks.length ? Buffer.concat(this.#stderrChunks) : Buffer.alloc(0);
+		let stderr = stderrBuf.toString('utf8');
+		if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
+		if (stderr) parts.push(`[stderr]\n${stderr}`);
+		return parts.join('\n');
+	}
 
-  /**
-   * Terminates process and its children (via pgrep).
-   *
-   * @param {number | string} [signal='SIGTERM'] - Signal to send.
-   * @returns {Promise<number[]>} Killed PIDs.
-   * @throws {Error} No process/PID.
-   */
-  async kill(signal = 'SIGTERM') {
-    if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
-    if (!this.#proc.pid) throw new Error('The process pid is undefined.');
-    this.#forcedKill = true;
-    const pid = this.#proc.pid;
-    let killed = [];
-    try {
-      const kids = await childrenOf(pid).catch(() => []);
-      for (const k of kids) {
-        try { process.kill(k, signal); killed.push(k); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
-      }
-      try { process.kill(pid, signal); killed.push(pid); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
-    } finally {
-      this.#proc = null;
-    }
-    return killed;
-  }
+	/**
+	 * Prefixes an error message with the received-output block when present.
+	 *
+	 * @private
+	 * @param {string} prefix - The primary error message (e.g. 'Process timed out after 500ms.').
+	 * @returns {string} `prefix` alone, or `prefix` + the formatted output block.
+	 */
+	#errorMessage(prefix) {
+		const output = this.#formatOutput();
+		return output ? `${prefix}\n${output}` : prefix;
+	}
 }
 
 export default SHExecute;