@j-o-r/sh 1.1.31 → 1.2.0

package/lib/internal.js

@@ -0,0 +1,179 @@
+/**
+ * Shared internals for the SH library.
+ *
+ * Single source of truth for the default command options used by the `SH`
+ * template tag (`lib/SH.js`) and `SHDispatch` (`lib/SHDispatch.js`), and for
+ * the shared `parseDuration` used by `lib/SH.js` and `lib/SHExecute.js`.
+ * Not part of the public API; nothing here is re-exported from `lib/SH.js`.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Explicit default `cwd` override, set via `SH.cwd = dir`.
+ *
+ * @type {string | undefined}
+ */
+let cwdOverride;
+
+/**
+ * Default maximum buffered bytes per stdout/stderr stream: 512000 (500 KiB).
+ * Used by `SHExecute` when `options.maxBuffer` is unset or invalid.
+ */
+const DEFAULT_MAX_BUFFER = 500 * 1024;
+
+/**
+ * Global (non-scoped) default option values, excluding the lazy `cwd`.
+ *
+ * `env` is a live reference to `process.env` by default. These are the values
+ * read/written by the `SH` proxy when no `within()` scope is active.
+ *
+ * @type {Omit<import('./SHDispatch.js').SHOptions, 'cwd'>}
+ */
+const globalDefaults = {
+	env: process.env,
+	shell: 'bash',
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 0, // absolute wall-clock timeout; 0 disables
+	maxBuffer: DEFAULT_MAX_BUFFER,
+	detached: false,
+};
+
+/**
+ * Per-`within()`-block option overrides.
+ *
+ * A plain object keyed by option name. A key present in the store shadows the
+ * global default for every command created inside the `within()` block; a key
+ * absent from the store inherits the enclosing scope (or the global default).
+ *
+ * @typedef {Object<string, any>} OptionScopeStore
+ */
+
+/**
+ * AsyncLocalStorage backing `within()` scoping (decision D2).
+ *
+ * `within()` runs its callback inside a fresh store seeded with a shallow copy
+ * of the enclosing store, so nested blocks inherit their parent's scoped
+ * values but never leak their own assignments outward. `getDefault`/`setDefault`
+ * consult the current store first and fall back to the global defaults.
+ *
+ * @type {AsyncLocalStorage<OptionScopeStore>}
+ */
+const optionScope = new AsyncLocalStorage();
+
+/**
+ * Reads the effective default for a key, honoring the current `within()` scope.
+ *
+ * A key present in the active scope store shadows the global default; `cwd`
+ * additionally falls back to the lazy `process.cwd()` resolution.
+ *
+ * @param {string} key - Option key.
+ * @returns {any} Effective default value.
+ */
+const getDefault = (key) => {
+	const store = optionScope.getStore();
+	if (store && store[key] !== undefined) return store[key];
+	if (key === 'cwd') return cwdOverride ?? process.cwd();
+	return globalDefaults[key];
+};
+
+/**
+ * Writes a default, scoping to the current `within()` block when active.
+ *
+ * Inside a `within()` block the assignment lands in the block's store and is
+ * discarded when the block ends; outside it mutates the global default.
+ *
+ * @param {string} key - Option key.
+ * @param {any} value - New default value.
+ */
+const setDefault = (key, value) => {
+	const store = optionScope.getStore();
+	if (store) { store[key] = value; return; }
+	if (key === 'cwd') { cwdOverride = value; return; }
+	globalDefaults[key] = value;
+};
+
+/**
+ * Default options applied to all SH commands unless overridden.
+ *
+ * `cwd` is intentionally lazy: the getter resolves `process.cwd()` at read
+ * time, so commands created after a `cd()` run in the new directory instead of
+ * the directory the process was started in. `SHDispatch` spreads these
+ * defaults (`{ ...defaultOptions }`) per command, which invokes the getters and
+ * freezes the values for that command — "defaults captured at creation time".
+ * Do not "optimize" this into a static snapshot.
+ *
+ * Every getter/setter is scope-aware: inside a `within()` block it reads/writes
+ * the block's scoped override (see {@link optionScope}); outside it reads/writes
+ * the global default. An explicit `SH.cwd = dir` assignment takes precedence
+ * over `process.cwd()` (it only redirects SH commands; it does not `chdir` the
+ * process). `cd()` clears the override again, so the most recent of the two
+ * always wins.
+ *
+ * @type {import('./SHDispatch.js').SHOptions}
+ */
+const defaultOptions = {};
+for (const key of ['cwd', ...Object.keys(globalDefaults)]) {
+	Object.defineProperty(defaultOptions, key, {
+		enumerable: true,
+		configurable: true,
+		get() { return getDefault(key); },
+		set(value) { setDefault(key, value); }
+	});
+}
+
+/**
+ * Known global option keys exposed by the `SH` proxy in `lib/SH.js`.
+ *
+ * Derived from the own keys of {@link defaultOptions}, so the key set can
+ * never drift from the defaults. (The previous hard-coded list in `lib/SH.js`
+ * readable-exposed `maxBuffer`/`detached`, which were uninitialized in the
+ * defaults.) The proxy routes reads/writes for these keys to
+ * `defaultOptions` and throws a `TypeError` on writes to any other key
+ * (decision D1).
+ *
+ * @type {Set<string>}
+ */
+const defaultOptionKeys = new Set(Object.keys(defaultOptions));
+
+/**
+ * Clears the `SH.cwd` override so the lazy `cwd` getter follows
+ * `process.cwd()` again. Called by `cd()` after a successful
+ * `process.chdir()`.
+ */
+const clearCwdOverride = () => {
+	cwdOverride = undefined;
+};
+
+/**
+ * Parses a human-readable duration into milliseconds.
+ *
+ * Accepts finite non-negative numbers (milliseconds) and strings in the exact
+ * forms `'Nms'`, `'Ns'`, or a bare `'N'`. The bare-number form is treated as
+ * milliseconds on purpose: it preserves the leniency of the former `SHExecute`
+ * parser, so e.g. `timeout: '100'` keeps working.
+ *
+ * `null`/`undefined` are not special-cased here; call sites that allow an
+ * absent duration handle it themselves (e.g. `parseDuration(timeout ?? 0)`).
+ *
+ * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms', '100').
+ * @returns {number} Duration in milliseconds.
+ * @throws {Error} If the duration type or format is invalid.
+ */
+const parseDuration = (d) => {
+	if (typeof d == 'number') {
+		if (!Number.isFinite(d) || d < 0)
+			throw new Error(`Invalid duration: "${d}".`);
+		return d;
+	}
+	if (typeof d == 'string') {
+		const match = d.match(/^(\d+)(ms|s)?$/);
+		if (!match)
+			throw new Error(`Unknown duration: "${d}".`);
+		const amount = Number(match[1]);
+		return match[2] == 's' ? amount * 1000 : amount;
+	}
+	throw new Error(`Invalid duration type: "${d === null ? 'Null' : typeof d}".`);
+};
+
+export { defaultOptions, defaultOptionKeys, clearCwdOverride, DEFAULT_MAX_BUFFER, parseDuration, optionScope };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.1.31",
+  "version": "1.2.0",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -22,7 +22,7 @@
   },
   "license": "Apache License, Version 2.0",
   "devDependencies": {
-    "@types/node": "^22.10.10"
+    "@types/node": "*"
   },
   "bugs": {
     "url": "https://codeberg.org/duin/sh/issues"
@@ -49,4 +49,4 @@
     "process-promise",
     "process-output"
   ]
-}
+}

package/types/SH.d.ts

@@ -7,11 +7,8 @@
 export type ArgsObject = {
     _: string[];
 } & {
-    [x: string]: string | true | string[];
+    [x: string]: string | true;
 };
-export type RejectCallback = Function;
-export type ResolveCallback = Function;
-export type SHOptions = import("./SHDispatch.js").SHOptions;
 export type AbortableInput = {
     /**
      * - Promise that resolves to user input or void if aborted.
@@ -23,9 +20,9 @@ export type AbortableInput = {
     abort: () => void;
 };
 /**
- * Generator-like object that yields retry delay durations.
+ * Generator that yields retry delay durations in milliseconds.
  */
-export type ExpBackoffGenerator = Iterator<number | string>;
+export type ExpBackoffGenerator = Generator<number, void, unknown>;
 /**
  * Template tag for building and executing shell commands.
  *
@@ -39,10 +36,15 @@ export type ExpBackoffGenerator = Iterator<number | string>;
  * command separators. It is not safe for untrusted input. Wrap untrusted values
  * with {@link bashEscape} before interpolating them.
  *
- * SH acts as both template tag and options setter: `SH.timeout = 5000; SH`cmd``
+ * SH also acts as a global options setter (see the last example). Global
+ * defaults are captured when each command is created, not when it runs — see
+ * the "defaults captured at creation time" note in {@link SHDispatch#options}.
+ * Only the known option keys (cwd, env, shell, stdio, timeout, maxBuffer,
+ * detached) may be assigned; assigning anything else throws a TypeError
+ * listing the known keys (typo guard, decision D1).
  *
  * @param {TemplateStringsArray} pieces - String literals from template.
- * @param {...unknown[]} args - Values to interpolate.
+ * @param {...unknown} args - Values to interpolate.
  * @returns {SHDispatch} Command dispatcher.
  * @throws {Error} If pieces contain undefined.
  * @example
@@ -54,11 +56,23 @@ export type ExpBackoffGenerator = Iterator<number | string>;
  *
  * // Quote untrusted values explicitly
  * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
+ *
+ * // Set global defaults for subsequently created commands
+ * SH.timeout = 5000;
+ * await SH`cmd`.run();
  */
 export const SH: any;
 /**
  * Changes the current working directory.
  *
+ * Affects the cwd of subsequent `SH` commands: default options capture
+ * `process.cwd()` lazily when each command is created. Also clears any
+ * `SH.cwd` override, so the most recent cwd change always wins.
+ *
+ * This is a genuine process-wide operation (`process.chdir`), so it is NOT
+ * scoped by {@link within}. Use `SH.cwd = dir` inside a `within()` block for a
+ * scoped working directory.
+ *
  * @param {string} dir - Path to new directory.
  * @example
  * cd('/tmp');
@@ -76,21 +90,29 @@ export function sleep(duration: string | number): Promise<void>;
 /**
  * Retries an async function up to N times with optional delays.
  *
- * Delay can be fixed ('1s'), generator-like (expBackoff()), or none.
+ * Delay precedence: when `delayOrCallback` is a function it is the retried
+ * callback and there is no delay between attempts. Otherwise it is a static
+ * duration ('1s', 100) or a delay generator (e.g. {@link expBackoff}), and
+ * `callback` is the retried function. A generator yield of `undefined`
+ * (exhausted generator) or `0` means "no further delay" — the next attempt
+ * runs immediately.
  *
  * @param {number} count - Positive integer number of attempts.
- * @param {string|number|ExpBackoffGenerator|Function} delayOrCallback - Delay, delay generator, or callback if no separate callback is supplied.
- * @param {Function} [callback] - Callback to retry when a delay is supplied.
+ * @param {string|number|Iterator<number|string>|(() => (Promise<any>|any))} delayOrCallback - Delay, delay generator, or the callback when no separate callback is supplied.
+ * @param {() => (Promise<any>|any)} [callback] - Callback to retry when a delay is supplied.
  * @returns {Promise<any>} Successful result.
  * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
  * @example
  * await retry(3, '1s', () => SH`curl http://unreliable`.run());
  * await retry(3, expBackoff(), () => flakyOp());
  */
-export function retry(count: number, delayOrCallback: string | number | ExpBackoffGenerator | Function, callback?: Function): Promise<any>;
+export function retry(count: number, delayOrCallback: string | number | Iterator<number | string> | (() => (Promise<any> | any)), callback?: () => (Promise<any> | any)): Promise<any>;
 /**
  * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
  *
+ * Side effect: permanently sets the `process.stdin` encoding to utf8 and
+ * switches it to flowing mode.
+ *
  * @returns {Promise<string>} Stdin content, or an empty string if TTY.
  * @example
  * const input = await readIn(); // Use in piped scripts
@@ -99,7 +121,14 @@ export function readIn(): Promise<string>;
 /**
  * Prompts user for input on stdin with custom prompt.
  *
- * Supports aborting input collection.
+ * Submit heuristics (non-obvious): each 'line' event is accumulated into a
+ * multi-line buffer and (re)starts a debounce timer
+ * ({@link SUBMIT_DEBOUNCE_MS}); when the timer fires without further input,
+ * the promise auto-resolves with the accumulated text plus any partially
+ * typed readline line. A paste — a stdin chunk longer than
+ * {@link PASTE_MIN_CHUNK} chars containing a newline — (re)starts the same
+ * timer, so pasted multi-line text resolves as one input. `abort()` resolves
+ * the promise with `undefined`.
  *
  * @param {string} prompt - Prompt text to display.
  * @returns {AbortableInput} Object with input Promise and abort function.
@@ -110,14 +139,24 @@ export function readIn(): Promise<string>;
  */
 export function userIn(prompt: string): AbortableInput;
 /**
- * Executes a callback in a new async context (fresh callstack).
+ * Awaits `callback()` and returns its result, running it in a fresh async
+ * context (decision D2).
+ *
+ * Real isolation via `AsyncLocalStorage`: the callback runs inside a new
+ * scope whose `SH.*` default-option assignments are scoped to the block. Any
+ * `SH.timeout = …`, `SH.cwd = …`, etc. made inside the callback apply only to
+ * commands created within it and are discarded when the block ends — they do
+ * not leak to the enclosing scope. Nested `within()` blocks inherit their
+ * parent's scoped defaults but never leak their own outward.
  *
- * Useful for parallel operations without nesting.
+ * Note: `cd()` is a genuine process-wide operation (`process.chdir`), so it is
+ * not scoped by `within()`; use `SH.cwd = dir` for a scoped working directory.
  *
  * @param {() => Promise<any>} callback - Async function to execute.
  * @returns {Promise<any>} Result of callback.
  * @example
  * const results = await within(async () => {
+ *   SH.timeout = 5000; // scoped to this block
  *   return Promise.all([SH`sleep 1; echo 1`.run(), sleep(2)]);
  * });
  */
@@ -129,18 +168,21 @@ export function within(callback: () => Promise<any>): Promise<any>;
  * @param {string} [max='60s'] - Max backoff duration.
  * @param {string} [rand='100ms'] - Max jitter.
  * @yields {number} Next backoff ms.
+ * @returns {ExpBackoffGenerator} Infinite generator of backoff delays in ms.
  * @example
  * const backoff = expBackoff();
  * await sleep(backoff.next().value);
  */
-export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
+export function expBackoff(max?: string, rand?: string): ExpBackoffGenerator;
 /**
  * Parses CLI arguments into an object.
  *
  * Supports --key value, -k value (no shorts grouped).
  * Bares go to _[]. Duplicates error. No = syntax.
  * Negative number tokens such as -1, -0.5, and -1e3 are parsed as values or
- * positionals, not options.
+ * positionals, not options. A lone `-` is a positional (stdin convention).
+ * `--` is the conventional end-of-options terminator: every token after it
+ * goes into `_`, even option-looking ones.
  *
  * Defaults to process.argv.slice(2).
  *
@@ -150,6 +192,8 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
  * @example
  * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
  * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
+ * parseArgs(['-', '--port', '1']); // { port: '1', _: ['-'] }
+ * parseArgs(['--', '--x']); // { _: ['--x'] }
  */
 export function parseArgs(args?: string[]): ArgsObject;
 /**
@@ -158,18 +202,7 @@ export function parseArgs(args?: string[]): ArgsObject;
  * Named options map to their string value, or `true` when no value is supplied.
  * Bare positional arguments are collected in `_`.
  *
- * @typedef {{_: string[]} & Object.<string, string|true|string[]>} ArgsObject
- */
-/**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
-/**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
-/**
- * @typedef {import('./SHDispatch.js').SHOptions} SHOptions
+ * @typedef {{_: string[]} & Object.<string, string|true>} ArgsObject
  */
 /**
  * @typedef {Object} AbortableInput
@@ -177,22 +210,29 @@ export function parseArgs(args?: string[]): ArgsObject;
  * @property {() => void} abort - Function to abort input collection.
  */
 /**
- * Generator-like object that yields retry delay durations.
+ * Generator that yields retry delay durations in milliseconds.
  *
- * @typedef {Iterator<number|string>} ExpBackoffGenerator
+ * @typedef {Generator<number, void, unknown>} ExpBackoffGenerator
  */
 /**
  * Utility to determine the JavaScript type of a value.
  *
- * @param {any} fn - Any value to inspect.
+ * Uses `Object.prototype.toString`, so `jsType(null)` returns `'Null'`;
+ * `undefined` is special-cased to `'undefined'`. Plain objects report their
+ * constructor name, or `'Object'` when there is none (null-prototype objects).
+ *
+ * @param {unknown} value - Any value to inspect.
  * @returns {string} The "real" object type name (e.g., 'Array', 'Promise') or primitive typeof.
  * @example
  * jsType([]); // 'Array'
  * jsType(Promise.resolve()); // 'Promise'
+ * jsType(null); // 'Null'
+ * jsType(undefined); // 'undefined'
  */
-export function jsType(fn: any): string;
+export function jsType(value: unknown): string;
 /**
- * Checks if an object has a specific own property (code-safe).
+ * Checks if an object has a specific own property. Safe for null-prototype
+ * objects and objects shadowing `hasOwnProperty`.
  *
  * @param {any} o - Object to examine.
  * @param {string} p - Property name to check.

package/types/SHDispatch.d.ts

@@ -1,30 +1,4 @@
 export default SHDispatch;
-export type SpawnSyncResponse = {
-    /**
-     * - Exit code (null if signal).
-     */
-    status: number | null;
-    /**
-     * - Terminating signal.
-     */
-    signal: string | null;
-    /**
-     * - [stdin, stdout, stderr].
-     */
-    output: (string | Buffer | null)[];
-    /**
-     * - Process ID.
-     */
-    pid: number;
-    /**
-     * - Captured stdout.
-     */
-    stdout: string | Buffer | null;
-    /**
-     * - Captured stderr.
-     */
-    stderr: string | Buffer | null;
-};
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
@@ -35,8 +9,8 @@ export type StdioOptions = Array<StdioOption> | StdioOption;
  * - `env`: `process.env`
  * - `shell`: `'bash'` (string/true → shell; false → no-shell `/usr/bin/env -S`)
  * - `stdio`: `['inherit', 'pipe', 'pipe']`
- * - `timeout`: `0` (no timeout; rolling on data)
- * - `maxBuffer`: `512000` (500 kb per stream in SHExecute)
+ * - `timeout`: `0` (no timeout; absolute wall-clock cap when set)
+ * - `maxBuffer`: `512000` (500 KiB per stream in SHExecute)
  *
  * Prefix (`.options(undefined, prefix)`) only for shell mode.
  */
@@ -58,7 +32,11 @@ export type SHOptions = {
      */
     stdio: StdioOptions;
     /**
-     * - Rolling timeout in ms or duration string; 0 disables timeout.
+     * - Absolute wall-clock timeout in ms or
+     * duration string; 0 disables. The process is killed after the full duration
+     * no matter how much output it produces, in BOTH `run()` and `runSync()`.
+     * This matches Node's native `spawn`/`spawnSync` `timeout` semantics; SH is
+     * not meant to run long-lived services, so there is no rolling/idle reset.
      */
     timeout: number | string;
     /**
@@ -66,7 +44,9 @@ export type SHOptions = {
      */
     maxBuffer?: number | undefined;
     /**
-     * - Run process detached and resolve early.
+     * - Run process detached and resolve early (~1s).
+     * Unless stdio is explicitly set for the command, stdio is forced to
+     * `'ignore'`, because open pipes would keep the parent's event loop alive.
      */
     detached?: boolean | undefined;
 };
@@ -104,6 +84,10 @@ declare class SHDispatch {
     /**
      * Async run: Captures stdout; rejects on error/timeout.
      *
+     * Replaces the internal process handle: calling `run()` again while a
+     * previous run is still active makes that first process unkillable via
+     * `kill()`.
+     *
      * @param {string} [payload] - Stdin payload.
      * @returns {Promise<string>} Stdout.
      */

package/types/SHExecute.d.ts

@@ -1,10 +1,9 @@
 export default SHExecute;
-export type SHExecuteOptions = any & {
-    maxBuffer?: number;
-};
+export type SHExecuteOptions = import("./SHDispatch.js").SHOptions;
 /**
- * @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).
  */
 /**
  * Low-level process executor for shell commands.
@@ -14,11 +13,27 @@ export type SHExecuteOptions = any & {
  * 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' });
@@ -34,6 +49,10 @@ declare class SHExecute {
     /**
      * 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.
@@ -42,18 +61,27 @@ declare class SHExecute {
     /**
      * Asynchronous execution with buffering/timeout/kill.
      *
-     * Resolves stdout (trimmed) on success; rejects on error/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).
-     * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
+     *   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?: string): Promise<string>;
     /**
-     * Terminates process and its children (via pgrep).
+     * 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.
+     * @returns {Promise<number[]>} Killed PIDs (the group-leader PID).
      * @throws {Error} No process/PID.
      */
     kill(signal?: number | string): Promise<number[]>;