@j-o-r/sh 1.1.32 → 1.2.0

package/lib/SH.js

@@ -31,7 +31,7 @@ import readline from 'node:readline/promises';
 import SHDispatch from './SHDispatch.js';
 import Test from './Test.js';
 import AsyncTracker from './AsyncTracker.js';
-import { defaultOptions, defaultOptionKeys, clearCwdOverride, parseDuration } from './internal.js';
+import { defaultOptions, defaultOptionKeys, clearCwdOverride, parseDuration, optionScope } from './internal.js';
 
 /**
  * Parsed command-line arguments.
@@ -189,23 +189,31 @@ const SH = new Proxy(function(pieces, ...args) {
 }, defaultOptionHandler);
 
 /**
- * Awaits `callback()` and returns its result.
+ * Awaits `callback()` and returns its result, running it in a fresh async
+ * context (decision D2).
  *
- * Despite the historical name, this is currently a thin wrapper: no new async
- * context or fresh callstack is created — the callback runs in the current
- * one. It is kept as an intent marker for grouping async work (and for API
- * compatibility); real isolation via AsyncLocalStorage is a pending decision
- * (see the project TODO, 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.
+ *
+ * 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)]);
  * });
  */
 const within = async (callback) => {
-	return await callback();
+	const parent = optionScope.getStore();
+	const store = { ...parent };
+	return optionScope.run(store, callback);
 };
 
 /**
@@ -398,6 +406,10 @@ const sleep = (duration) => {
  * `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');

package/lib/SHDispatch.js

@@ -24,7 +24,7 @@ import { defaultOptions } from './internal.js';
  * - `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)
+ * - `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.
@@ -34,10 +34,11 @@ import { defaultOptions } from './internal.js';
  * @property {NodeJS.ProcessEnv} env - Environment for spawned commands.
  * @property {string|boolean} shell - Shell executable, true for bash, or false for no-shell mode.
  * @property {StdioOptions} stdio - Stdio config passed to child_process.
- * @property {number|string} timeout - Timeout in ms or duration string; 0 disables.
- *   Async `run()` uses a rolling timeout that resets on stdout/stderr data.
- *   `runSync()` passes it to `spawnSync`, where it is absolute: the process is
- *   killed after the full duration no matter how much output it produces.
+ * @property {number|string} 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.
  * @property {number} [maxBuffer] - Maximum buffered bytes per stdout/stderr stream.
  * @property {boolean} [detached] - Run process detached and resolve early (~1s).
  *   Unless stdio is explicitly set for the command, stdio is forced to

package/lib/SHExecute.js

@@ -2,31 +2,10 @@ import { spawnSync, spawn } from 'node:child_process';
 import { DEFAULT_MAX_BUFFER, parseDuration } from './internal.js';
 
 /**
- * Retrieves child PIDs of a given parent PID using pgrep -P.
- *
- * Best-effort: any pgrep failure resolves to an empty list so callers
- * (notably `kill()`) always settle instead of hanging.
- *
- * @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
-		} else {
-			// pgrep failed (2: syntax error, 3: fatal error); kill stays best-effort.
-			resolve([]);
-		}
-	});
-	p.on('error', reject);
-});
+const ESCALATION_GRACE_MS = 1000;
 
 /**
  * @typedef {import('./SHDispatch.js').SHOptions} SHExecuteOptions
@@ -42,17 +21,27 @@ 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.
- *   Async `run()` only — the timeout is stripped from the spawn options so Node's
- *   native absolute spawn timeout never interferes. `runSync()` instead passes the
- *   timeout to `spawnSync`, whose semantics are absolute (kills after the full
- *   duration, regardless of output).
+ * - **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. 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 process + direct children via pgrep (requires procps; grandchildren survive).
+ * - **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' });
@@ -73,8 +62,10 @@ class SHExecute {
 	#maxBuffer = DEFAULT_MAX_BUFFER; // 512000 bytes (500 KiB) per stream
 	#truncated = { stdout: false, stderr: false };
 	#timedOut = false;
-	/** Timeout in ms; 0 disables. Rolling in `run()`, absolute in `runSync()`. */
+	/** 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.
@@ -84,9 +75,9 @@ class SHExecute {
 	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 rolling timeout in run().
+		// 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);
@@ -96,6 +87,10 @@ 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.
@@ -107,8 +102,9 @@ class SHExecute {
 		}
 		/** @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) {
-			// spawnSync supports timeout natively; semantics are absolute (no rolling reset).
 			options.timeout = this.#timeout;
 		}
 		if (payload) {
@@ -137,16 +133,22 @@ class SHExecute {
 	 * @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 stderr), rolling-timeout expiry,
-	 *   forced kill, or spawn failure.
+	 *   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 };
+		const options = { ...this.#options, shell: false, detached: true };
 		if (payload) {
 			const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
 			stdio[0] = 'pipe';
@@ -161,6 +163,7 @@ class SHExecute {
 		this.#stderrLen = 0;
 		this.#truncated = { stdout: false, stderr: false };
 		this.#timedOut = false;
+		this.#escalationTimer = null;
 
 		const shellOpt = this.#options?.shell;
 		if (shellOpt) {
@@ -173,19 +176,19 @@ class SHExecute {
 
 		if (payload) this.#proc.stdin?.end(payload);
 
-		const ms = this.#timeout;
-		let timeoutId = null;
-		const resetTimeout = () => {
-			if (timeoutId !== null) clearTimeout(timeoutId);
-			if (ms > 0) {
-				timeoutId = setTimeout(() => {
-					this.#timedOut = true;
-					this.kill('SIGTERM').catch(() => {});
-				}, ms);
-			}
+		const timeoutMs = this.#timeout;
+		let timeoutTimer = null;
+		/** @type {number} The timeout (ms) that actually fired, for the error message. */
+		let firedMs = 0;
+
+		const killOnTimeout = (ms) => {
+			firedMs = ms;
+			this.#timedOut = true;
+			this.kill('SIGTERM').catch(() => {});
 		};
 
-		if (ms > 0) resetTimeout();
+		// Timeout is absolute: never reset on output.
+		if (timeoutMs > 0) timeoutTimer = setTimeout(() => killOnTimeout(timeoutMs), timeoutMs);
 
 		this.#proc.stdout?.on('data', (chunk) => {
 			this.#stdoutLen += chunk.length;
@@ -195,7 +198,6 @@ class SHExecute {
 			} else {
 				this.#truncated.stdout = true;
 			}
-			resetTimeout();
 		});
 
 		this.#proc.stderr?.on('data', (chunk) => {
@@ -205,13 +207,12 @@ class SHExecute {
 			} else {
 				this.#truncated.stderr = true;
 			}
-			resetTimeout();
 		});
 
 		return new Promise((resolve, reject) => {
-			if (options.detached) {
+			if (publicDetached) {
 				setTimeout(() => {
-					if (timeoutId !== null) clearTimeout(timeoutId);
+					if (timeoutTimer !== null) clearTimeout(timeoutTimer);
 					resolve('');
 					// #proc may already be null when kill() ran within the 1s window.
 					this.#proc?.unref();
@@ -219,15 +220,19 @@ class SHExecute {
 			}
 
 			this.#proc.on('close', (code, signal) => {
-				if (timeoutId !== null) clearTimeout(timeoutId);
+				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(`Process timed out after ${ms}ms.`));
+					reject(new Error(this.#errorMessage(`Process timed out after ${firedMs}ms.`)));
 					return;
 				}
 				if (this.#forcedKill) {
-					reject(new Error('Process killed (forced).'));
+					reject(new Error(this.#errorMessage('Process killed (forced).')));
 					return;
 				}
 				if (code === 0) {
@@ -236,11 +241,8 @@ class SHExecute {
 					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';
 					const reason = code === null ? `signal ${signal}` : `code ${code}`;
-					reject(new Error(`Command failed with ${reason}: ${stderr}`));
+					reject(new Error(this.#errorMessage(`Command failed with ${reason}.`)));
 				}
 			});
 
@@ -249,14 +251,16 @@ class SHExecute {
 	}
 
 	/**
-	 * Terminates process and its children (via pgrep).
+	 * Terminates the whole process group (negative-PID kill).
 	 *
-	 * Requires `pgrep` (procps) at runtime. Only direct children are
-	 * discovered — grandchildren and deeper descendants survive. Best-effort:
-	 * pgrep failures resolve to an empty child list instead of rejecting.
+	 * 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.
 	 */
 	async kill(signal = 'SIGTERM') {
@@ -264,18 +268,74 @@ class SHExecute {
 		if (!this.#proc.pid) throw new Error('The process pid is undefined.');
 		this.#forcedKill = true;
 		const pid = this.#proc.pid;
-		let killed = [];
+		const 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; }
+			// 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);
 			}
-			try { process.kill(pid, signal); killed.push(pid); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
 		} finally {
 			this.#proc = null;
 		}
 		return killed;
 	}
+
+	/**
+	 * 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);
+	}
+
+	/**
+	 * 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');
+	}
+
+	/**
+	 * 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;

package/lib/internal.js

@@ -7,6 +7,8 @@
  * 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`.
  *
@@ -20,41 +22,105 @@ let cwdOverride;
  */
 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 getter and
- * freezes the value for that command — "defaults captured at creation time".
+ * 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.
  *
- * 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.
- *
- * `maxBuffer` and `detached` are initialized explicitly so every key the `SH`
- * proxy exposes ({@link defaultOptionKeys}) also has a defined value here.
- * This is behavior-neutral: `SHExecute` already fell back to
- * `DEFAULT_MAX_BUFFER` for unset/invalid values and truthy-checks `detached`.
+ * 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 = {
-	get cwd() {
-		return cwdOverride ?? process.cwd();
-	},
-	set cwd(value) {
-		cwdOverride = value;
-	},
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0, // when 0 there is no timeout
-	maxBuffer: DEFAULT_MAX_BUFFER,
-	detached: false,
-};
+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`.
@@ -110,4 +176,4 @@ const parseDuration = (d) => {
 	throw new Error(`Invalid duration type: "${d === null ? 'Null' : typeof d}".`);
 };
 
-export { defaultOptions, defaultOptionKeys, clearCwdOverride, DEFAULT_MAX_BUFFER, parseDuration };
+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.32",
+  "version": "1.2.0",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/SH.d.ts

@@ -69,6 +69,10 @@ export const SH: any;
  * `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');
@@ -135,18 +139,24 @@ export function readIn(): Promise<string>;
  */
 export function userIn(prompt: string): AbortableInput;
 /**
- * Awaits `callback()` and returns its result.
+ * 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.
  *
- * Despite the historical name, this is currently a thin wrapper: no new async
- * context or fresh callstack is created — the callback runs in the current
- * one. It is kept as an intent marker for grouping async work (and for API
- * compatibility); real isolation via AsyncLocalStorage is a pending decision
- * (see the project TODO, decision D2).
+ * 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)]);
  * });
  */

package/types/SHDispatch.d.ts

@@ -9,7 +9,7 @@ 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)
+ * - `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.
@@ -32,10 +32,11 @@ export type SHOptions = {
      */
     stdio: StdioOptions;
     /**
-     * - Timeout in ms or duration string; 0 disables.
-     * Async `run()` uses a rolling timeout that resets on stdout/stderr data.
-     * `runSync()` passes it to `spawnSync`, where it is absolute: the process is
-     * killed after the full duration no matter how much output it produces.
+     * - 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;
     /**

package/types/SHExecute.d.ts

@@ -13,17 +13,27 @@ export type SHExecuteOptions = import("./SHDispatch.js").SHOptions;
  * 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.
- *   Async `run()` only — the timeout is stripped from the spawn options so Node's
- *   native absolute spawn timeout never interferes. `runSync()` instead passes the
- *   timeout to `spawnSync`, whose semantics are absolute (kills after the full
- *   duration, regardless of output).
+ * - **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. 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 process + direct children via pgrep (requires procps; grandchildren survive).
+ * - **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' });
@@ -39,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.
@@ -52,19 +66,22 @@ declare class SHExecute {
      * @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 stderr), rolling-timeout expiry,
-     *   forced kill, or spawn failure.
+     *   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).
      *
-     * Requires `pgrep` (procps) at runtime. Only direct children are
-     * discovered — grandchildren and deeper descendants survive. Best-effort:
-     * pgrep failures resolve to an empty child list instead of rejecting.
+     * 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[]>;

package/types/internal.d.ts

@@ -1,21 +1,29 @@
+/**
+ * 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).
+ */
+export type OptionScopeStore = {
+    [x: string]: any;
+};
 /**
  * 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 getter and
- * freezes the value for that command — "defaults captured at creation time".
+ * 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.
  *
- * 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.
- *
- * `maxBuffer` and `detached` are initialized explicitly so every key the `SH`
- * proxy exposes ({@link defaultOptionKeys}) also has a defined value here.
- * This is behavior-neutral: `SHExecute` already fell back to
- * `DEFAULT_MAX_BUFFER` for unset/invalid values and truthy-checks `detached`.
+ * 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}
  */
@@ -60,3 +68,24 @@ export const DEFAULT_MAX_BUFFER: number;
  * @throws {Error} If the duration type or format is invalid.
  */
 export function parseDuration(d: number | string): number;
+/**
+ * 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>}
+ */
+export const optionScope: AsyncLocalStorage<OptionScopeStore>;
+import { AsyncLocalStorage } from 'node:async_hooks';

package/.editorconfig

@@ -1,21 +0,0 @@
-root = true
-
-# Project standard: tab indentation for JavaScript (STRUCT-3).
-# lib/** is fully conformant; some scenarios/*.js demos predate this
-# standard and are intentionally left as-is (no mass reformat there).
-[*]
-indent_style = tab
-indent_size = tab
-charset = utf-8
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.{json,yml,yaml}]
-indent_style = space
-indent_size = 2
-
-[*.md]
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = false

package/TODO.md

@@ -1,355 +0,0 @@
-# TODOs for @j-o-r/sh project
-
-## lib/SH.js review findings (2026-06-26)
-
-Source: full code review of `lib/SH.js`, `lib/SHDispatch.js`, `lib/SHExecute.js`.
-Work through Pass 1 first (behavioral bugs), then Pass 2 (docs/typedefs), then Pass 3 (structure/style).
-Each item lists: file(s), problem, fix, acceptance criteria. Check the Decision Points section before
-implementing anything marked with a D-number.
-
-### Context for the implementing agent
-
-- Package: `@j-o-r/sh` v1.1.31, ESM (`"type": "module"`), Node >= 20, zero runtime dependencies.
-- Layering: `lib/SH.js` (public API: template tag, helpers, re-exports) → `lib/SHDispatch.js`
-  (per-command option merging, chaining) → `lib/SHExecute.js` (spawn/spawnSync wrapper).
-- Public typings are **generated from JSDoc**: `npm run types` runs `tsc -p tsc.json` into `types/`.
-  Any JSDoc error becomes a public API type error. Always regenerate types after doc changes.
-- Tests: `npm test` → `scenarios/sh.js`. Add scenario coverage for every Pass 1 fix.
-- Do not change public API signatures unless a Decision point explicitly approves it.
-
----
-
-### Pass 1 — Behavioral fixes (ALL DONE 2026-07-28)
-
-#### FIX-1 (P1) — DONE 2026-07-28: `cd()` does not affect subsequent `SH` commands (stale cwd)
-
-- **Files:** `lib/SH.js` (`defaultOptions.cwd = process.cwd()` captured at module load; `cd()` only
-  calls `process.chdir()`), `lib/SHDispatch.js` (duplicated `defaultSHOptions` with a second snapshot).
-- **Symptom:** `cd('/tmp'); await SH`pwd`.run()` still executes in the directory the process was
-  started in.
-- **Root cause:** `process.cwd()` is snapshotted once at module load, and `mergeOptions` copies that
-  stale value into every dispatch instance.
-- **Fix:**
-  1. Create a single shared defaults source — new file `lib/internal.js` exporting `defaultOptions`
-     (see STRUCT-1). Delete the duplicated `defaultSHOptions` in `lib/SHDispatch.js`.
-  2. Make `cwd` lazy, so it reflects the cwd at command-creation time, not module-load time:
-     ```js
-     const defaultOptions = {
-       get cwd() { return process.cwd(); },
-       env: process.env,
-       shell: 'bash',
-       stdio: ['inherit', 'pipe', 'pipe'],
-       timeout: 0,
-     };
-     ```
-     Note: `SHDispatch.options()` spreads `{ ...options }`, which invokes the getter and freezes the
-     value per dispatch instance. That is correct and intended ("defaults captured when the command
-     was created") — a `new SHDispatch` is created per `SH`cmd`` evaluation, i.e. after any `cd()`.
-     Do not "optimize" this away.
-  3. Alternative (acceptable but less informative): omit `cwd` from defaults entirely; `spawn` then
-     uses the current process cwd at spawn time. If chosen, keep a `SH.cwd` readback working somehow.
-- **Acceptance:** new scenario: `cd(tmpdir)` then `await SH`pwd`.run()` resolves to that tmpdir.
-
-#### FIX-2 (P1) — DONE 2026-07-28: Rolling timeout is defeated by Node's native spawn timeout
-
-- **File:** `lib/SHExecute.js`, constructor: `const { maxBuffer, ...spawnOpts } = options ?? {};`
-  strips `maxBuffer` but leaves `timeout` inside `spawnOpts`, which is passed to `spawn()`.
-- **Root cause:** since Node 15.5, `spawn` accepts `timeout` and kills the process after an
-  *absolute* duration, regardless of output. This breaks the documented rolling timeout
-  (reset on stdout/stderr data) and produces a misleading `Command failed with code null` rejection.
-- **Fix:** also destructure `timeout` out of the options; store it in a private field (e.g.
-  `#timeout`) and use it exclusively for the rolling timer in `run()`. In `runSync()`, re-add
-  `timeout` to the `spawnSync` options (supported natively; semantics are absolute — document this
-  sync/async difference in the `SHOptions` typedef).
-- **Acceptance:** scenario with a command that emits output continuously for longer than `timeout`
-  and exits 0 → succeeds; a command that goes silent → killed ~`timeout` ms after its last output.
-
-#### FIX-3 (P1) — DONE 2026-07-28: Timeout rejection reports the wrong error message
-
-- **File:** `lib/SHExecute.js`, `run()` close handler: `this.#forcedKill` is checked **before**
-  `this.#timedOut`.
-- **Root cause:** the timeout path sets `#timedOut = true` and immediately calls `kill('SIGTERM')`,
-  which sets `#forcedKill = true` in the same tick. The forced-kill branch always wins, so
-  `Process timed out after ${ms}ms.` is unreachable — timeouts report `Process killed (forced).`.
-- **Fix:** check `#timedOut` before `#forcedKill` in the close handler.
-- **Acceptance:** timeout rejection message matches `/timed out after \d+ms/`.
-
-#### FIX-4 (P1) — DONE 2026-07-28: `childrenOf()` can hang `kill()` forever
-
-- **File:** `lib/SHExecute.js`, `childrenOf()`: the `close` handler resolves for pgrep exit codes
-  `0` and `1` only. Exit codes 2 (syntax error) / 3 (fatal error) never settle the promise, and
-  `SHDispatch.kill()` awaits it indefinitely.
-- **Fix:** add a final `else resolve([]);` (kill is already best-effort; an unexpected pgrep failure
-  should not wedge the library).
-- **Acceptance:** code inspection + comment; `kill()` is guaranteed to settle on all pgrep outcomes.
-
-#### FIX-5 (P1) — DONE 2026-07-28: Detached mode — null deref crash + incomplete detachment
-
-- **File:** `lib/SHExecute.js`, `run()` detached branch.
-- **Bug A:** the 1-second `setTimeout` callback calls `this.#proc.unref()` unguarded. If `kill()`
-  runs within that window, `#proc` is `null` → `TypeError` crashes the process.
-  **Fix:** `this.#proc?.unref();`.
-- **Bug B:** with the default piped stdio, the parent's pipe handles keep the event loop alive even
-  after `unref()`, so the parent cannot actually exit early. **Fix:** when `options.detached` is
-  true and the user did not explicitly provide `stdio`, force `stdio: 'ignore'`; if the user did
-  provide stdio, keep it and document that pipes keep the parent alive. Update the class JSDoc
-  ("Detached" bullet) accordingly.
-- **Acceptance:** detached + immediate `kill()` does not crash; JSDoc states the stdio behavior.
-
-#### FIX-6 (P2) — DONE 2026-07-28: `parseArgs` mishandles lone `-` and `--`
-
-- **File:** `lib/SH.js`. `isOptionArg('-')` is true → produces an empty-string key `''` and consumes
-  the next token as its value. `--` (conventional end-of-options marker) also becomes key `''`.
-- **Fix:** treat lone `-` as a positional (stdin convention). Treat `--` as end-of-options
-  terminator: all following tokens go into `_` (see D4). Update the `parseArgs` JSDoc.
-- **Acceptance:** `parseArgs(['-', '--port', '1'])` → `{ port: '1', _: ['-'] }`;
-  `parseArgs(['--', '--x'])` → `{ _: ['--x'] }`.
-
----
-
-### Pass 2 — JSDoc / typedef correctness (ALL DONE 2026-07-28)
-
-- **DOC-1** — DONE 2026-07-28: Remove dead typedefs in `lib/SH.js`: `RejectCallback`, `ResolveCallback`, and the
-  `SHOptions` re-typedef. Repoint `lib/SHExecute.js`'s `SHExecuteOptions` to
-  `import('./SHDispatch.js').SHOptions` directly and drop the redundant `& { maxBuffer?: number }`
-  (`maxBuffer` is already optional in `SHOptions`). Regenerate types; grep for dangling references.
-- **DOC-2** — DONE 2026-07-28: Fix inaccurate typedefs in `lib/SH.js`: `ExpBackoffGenerator` — `expBackoff` only
-  yields numbers, so use `Generator<number, void, unknown>` (if string-yielding generators must stay
-  valid for `retry`, type retry's param as `Iterator<number|string>` explicitly instead);
-  `ArgsObject` — remove `string[]` (duplicates throw; arrays are never produced);
-  `SH` tag — `@param {...unknown[]} args` → `{...unknown}`.
-- **DOC-3** — DONE 2026-07-28: `jsType` (`lib/SH.js`): rename param `fn` → `value`, type `unknown`; fix the
-  null-prototype crash (`fn.constructor?.name ?? 'Object'`); fix the doc — `jsType(null)` returns
-  `'Null'`, and `undefined` is special-cased to `'undefined'`.
-- **DOC-4** — DONE 2026-07-28: `within` (`lib/SH.js`): implementation is `await callback()` (a no-op wrapper) but the
-  doc promises "a new async context (fresh callstack)". Reword the doc now; real isolation is
-  Decision D2.
-- **DOC-5** — DONE 2026-07-28: `maxBuffer` default doc drift: actual default is `512000` (`500 * 1024`). Fix
-  `lib/SHExecute.js` class JSDoc ("1MB default") and `SHExecuteOptions` typedef ("default 1MB") —
-  both wrong. Standardize on `512000 (500 KiB)` everywhere; ideally one constant in
-  `lib/internal.js` (STRUCT-1).
-- **DOC-6** — DONE 2026-07-28: `userIn` (`lib/SH.js`): document the non-obvious submit heuristics — 'line' event +
-  50 ms debounce auto-resolve, paste detection via `chunk.length > 4 && chunk.includes('\n')`,
-  multi-line accumulation, `abort()` resolving with `undefined`. Lift magic numbers into named
-  constants (e.g. `PASTE_MIN_CHUNK = 4`, `SUBMIT_DEBOUNCE_MS = 50`).
-- **DOC-7** — DONE 2026-07-28: `readIn` (`lib/SH.js`): document the side effect — permanently sets
-  `process.stdin` encoding to utf8 and switches it to flowing mode.
-- **DOC-8** — DONE 2026-07-28: `retry` (`lib/SH.js`): replace `{Function}` param types with explicit signatures
-  (e.g. `{() => (Promise<any>|any)}`); document delay precedence and that an exhausted generator
-  means "no further delay".
-- **DOC-9** — DONE 2026-07-28: `lib/SHDispatch.js`: remove the dead `SpawnSyncResponse` typedef; change constructor
-  error `'Undefined command'` → `'Invalid or empty command'`; document that `run()` replaces
-  `#proc`, so a second concurrent `run()` makes the first unkillable via `kill()`.
-- **DOC-10** — DONE 2026-07-28: `lib/SHExecute.js`: async `run()` says `@throws` — use "rejects with" wording;
-  document the `pgrep` (procps) runtime dependency of `kill()` and the direct-children-only
-  limitation (grandchildren survive); fix the failure message for signal kills (`code` is `null`,
-  printing "code null") — include `signal` in the message. Structured errors: see D3.
-- **DOC-11** — DONE 2026-07-28: `SH` tag JSDoc (`lib/SH.js`): the inline `` `SH.timeout = 5000; SH`cmd`` `` breaks
-  markdown rendering (nested backticks) — move it into an `@example` block; cross-link the
-  "defaults captured at creation time" note from `SHDispatch`.
-- **DOC-12** — DONE 2026-07-28: `hasProp` (`lib/SH.js`): replace "(code-safe)" with "safe for null-prototype objects
-  and objects shadowing `hasOwnProperty`". Optionally simplify to `Object.hasOwn` (Node >= 16.9;
-  engines require >= 20).
-
----
-
-### Pass 3 — Structure & style
-
-- **STRUCT-1** — DONE 2026-07-28: Single source of truth — create `lib/internal.js` exporting `defaultOptions`
-  (with lazy `cwd`, see FIX-1) and one shared `parseDuration`. Import it from `SH.js`,
-  `SHDispatch.js`, `SHExecute.js`. This removes the duplicated `defaultSHOptions`
-  (`lib/SHDispatch.js`) and the divergent second `parseDuration` (`lib/SHExecute.js` — currently
-  accepts bare `'100'` and `null → 0`, while `lib/SH.js`'s throws). Unified semantics: finite
-  numbers >= 0 (ms); strings `'Nms'`, `'Ns'`, or bare `'N'` (= ms, preserving SHExecute's current
-  leniency — document it); descriptive errors from the SH.js version; `null`/`undefined` handled at
-  call sites (`timeout ?? 0`).
-- **STRUCT-2** — DONE 2026-08-05: Proxy symmetry (`lib/SH.js`): the `set` trap accepted any
-  property but `get` exposed only `defaultOptionKeys`, so `SH.foo = 1; SH.foo` === `undefined`.
-  Implemented D1 (throw). Aligned `defaultOptionKeys` with the defaults object by deriving it
-  from `defaultOptions` and initializing `maxBuffer`/`detached` in the defaults.
-- **STRUCT-3** — DONE 2026-08-05: Formatting unified: tabs everywhere in `lib/` (`SH.js` mixed
-  and `SHExecute.js` 2-space converted), semicolon drift fixed in `lib/SH.js`. `.editorconfig`
-  added (tabs for JS; 2-space for JSON/MD/YAML). One commit, **no** logic changes (proven by
-  `git diff -w`: only added semicolons). Scenario files intentionally not mass-reformatted.
-- **STRUCT-4** — DONE 2026-08-05: `@ts-ignore` audit: `parseArgs` return — replaced with an
-  `ArgsObject`-typed declaration; `cd`'s `@ts-ignore` on `process.chdir` — verified with tsc and
-  removed; reason comments added to every remaining `@ts-ignore` (lib + scenarios).
-
----
-
-### Decision points (confirm with maintainer first)
-
-- **D1 — proxy `set` for unknown keys:** (a) throw `TypeError` listing known keys (catches typos
-  like `SH.timout = 1`; breaking for anyone setting custom props), or (b) store custom keys in a
-  separate `Map` and read them back (function props like `name` must not be shadowed).
-  Recommended: (a).
-  **DECIDED 2026-08-05: (a)** — throw a TypeError listing the known keys (implemented in STRUCT-2).
-- **D2 — `within()`:** implement real isolation via `AsyncLocalStorage` (larger change; would also
-  enable per-call default scoping) or keep the wrapper and just fix the docs (DOC-4).
-  Recommended short-term: docs only.
-- **D3 — structured failure errors:** reject with an error carrying `code`/`signal`/`stdout`/
-  `stderr` (zx `ProcessOutput` precedent). Public API change — defer to next major. Minimal fix for
-  now is in DOC-10.
-- **D4 — `--` semantics in `parseArgs`:** standard end-of-options terminator (recommended) vs
-  treating `--` as a positional. Affects FIX-6.
-  **DECIDED 2026-07-28: terminator** (as encoded in the FIX-6 acceptance criteria).
-- **D5 — API-surface trim:** re-exporting `node:assert`, `Test`, `AsyncTracker`, plus generic utils
-  (`jsType`, `hasProp`, `parseArgs`) blurs the "lean shell bridge" mission stated in the file
-  header. Consider deprecating the `assert` re-export. Non-blocking.
-
----
-
-### Verification checklist (run before moving items to Done)
-
-- [x] `npm test` passes, including new scenarios for FIX-1 … FIX-6 and STRUCT-2 (30/30; FIX-4 covered by code inspection per its acceptance criteria).
-- [x] `npm run types` regenerates `types/` with zero errors (new `types/internal.d.ts`).
-- [x] `grep -rn "RejectCallback\|ResolveCallback\|SpawnSyncResponse" lib/ types/` returns nothing
-      after DOC-1 / DOC-9 (verified 2026-07-28).
-- [x] Manual smoke: `cd` + `pwd`; chatty command with rolling timeout; timeout error message;
-      detached + immediate kill; `parseArgs` with `-` and `--` — all automated as the
-      FIX-1…FIX-6 scenario block in `scenarios/sh.js`.
-
-## In Progress
-
-## Done
-
-### Pass 1 — completed 2026-07-28
-
-- **FIX-1** — `lib/internal.js` created as the single defaults source with a lazy `cwd`
-  getter. Design refinement vs the sketched getter-only snippet: a setter keeps `SH.cwd = dir`
-  working (a getter-only accessor would throw on assignment in strict mode), and `cd()` clears
-  the override via `clearCwdOverride()` — the most recent of `cd()` / `SH.cwd =`
-  always wins. Duplicated `defaultSHOptions` removed from `lib/SHDispatch.js`. Scenario 24.
-- **FIX-2** — `timeout` destructured out of the spawn options into `#timeout`
-  (`lib/SHExecute.js`), used only for the rolling timer in `run()`; `runSync()`
-  re-adds it to `spawnSync` (native, absolute). Sync/async difference documented in the
-  `SHOptions` typedef. Scenario 25 (chatty command ~2s survives a 500 ms rolling timeout).
-- **FIX-3** — `#timedOut` is checked before `#forcedKill` in the close handler.
-  Scenario 25 asserts `/timed out after 400ms/`.
-- **FIX-4** — `childrenOf()` gained a final `else resolve([])` (pgrep exit 2/3) with
-  comment; `kill()` settles on all pgrep outcomes. Acceptance was code inspection — no scenario.
-- **FIX-5** — `this.#proc?.unref()`; `SHDispatch.run()` forces `stdio: 'ignore'`
-  when `detached` and stdio was not explicitly provided (tracked via `#stdioProvided`);
-  JSDoc updated (`SHExecute` class bullet, `SHOptions.detached`). Scenarios 26–27.
-- **FIX-6** — `isOptionArg` requires length > 1 (lone `-` → positional / option value);
-  `--` terminates option parsing (D4: terminator). `parseArgs` JSDoc + examples updated.
-  Scenario 28; standalone `scenarios/parse_args.js` still passes (6/6).
-
-Validation run: `node --check` on all changed files OK; `npm test` 29/29;
-`npm run types` exit 0; `node scenarios/parse_args.js` 6/6.
-
-### Pass 2 — completed 2026-07-28
-
-- **DOC-1** — Dead `RejectCallback`/`ResolveCallback`/`SHOptions` re-typedefs removed from
-  `lib/SH.js`; `SHExecuteOptions` repointed to `import('./SHDispatch.js').SHOptions`
-  (redundant `& { maxBuffer?: number }` dropped).
-- **DOC-2** — `ArgsObject` no longer includes `string[]`; `ExpBackoffGenerator` is
-  `Generator<number, void, unknown>` (kept alive via `@returns` on `expBackoff`;
-  `retry` types its delay param as `Iterator<number|string>`); SH tag `{...unknown}`.
-- **DOC-3** — `jsType` param renamed `fn` → `value` (`unknown`), null-prototype
-  crash fixed (`constructor?.name ?? 'Object'`), docs cover `'Null'`/`'undefined'`.
-- **DOC-4** — `within` doc reworded: thin wrapper, no isolation; D2 referenced.
-- **DOC-5** — `DEFAULT_MAX_BUFFER` constant in `lib/internal.js` (500 * 1024); `SHExecute`
-  uses it; all docs standardized on `512000 (500 KiB)`.
-- **DOC-6** — `userIn` heuristics documented; `PASTE_MIN_CHUNK`/`SUBMIT_DEBOUNCE_MS` constants.
-- **DOC-7** — `readIn` stdin encoding/flowing side effect documented.
-- **DOC-8** — `retry` params typed with explicit signatures; delay precedence + exhausted-generator
-  semantics documented.
-- **DOC-9** — `SpawnSyncResponse` typedef removed; constructor error now `'Invalid or empty
-  command'`; `run()` documents the concurrent-run unkillable caveat.
-- **DOC-10** — async `run()` uses rejects-with wording; `kill()` documents the procps/`pgrep`
-  dependency and direct-children-only limit; signal kills now report `signal <SIG>` instead of
-  `code null`.
-- **DOC-11** — nested-backtick inline moved into `@example`; cross-link to `SHDispatch#options`.
-- **DOC-12** — `hasProp` doc reworded; body simplified to `Object.hasOwn`.
-
-Validation run: `node --check` OK on all changed files; `npm test` 29/29; `npm run types`
-exit 0; dead-typedef grep clean; `SH: any` in `types/SH.d.ts` unchanged (pre-existing).
-
-### STRUCT-1 (Pass 3) — completed 2026-07-28
-
-- **STRUCT-1** — `parseDuration` unified in `lib/internal.js` alongside `defaultOptions`.
-  The divergent copies in `lib/SH.js` (strict) and `lib/SHExecute.js` (lenient) were
-  deleted; both now import from `./internal.js` (`SHExecute`'s now-dead `isFinitePosInt`
-  helper removed too). Unified semantics as specified: finite numbers >= 0 (ms); strings
-  `'Nms'`, `'Ns'`, or bare `'N'` (= ms, leniency documented in the JSDoc); descriptive
-  SH.js-style errors; `null`/`undefined` handled at call sites (`SHExecute` already had
-  `timeout ?? 0`). Scenario 13 in `scenarios/sh.js` updated to the unified semantics —
-  it previously asserted the old strict SH.js behavior by rejecting bare `'5'`; renamed to
-  'duration parsing' and extended with bare-string acceptance coverage. Minor deviation:
-  the invalid-type error message uses `typeof` instead of `jsType` (avoids an
-  internal↔SH import cycle; e.g. 'boolean' instead of 'Boolean' — no test relied on it).
-
-Validation run: `node --check` on all changed files OK; `npm test` 29/29;
-`npm run types` exit 0 (`types/internal.d.ts` now exports `parseDuration`);
-`node scenarios/parse_args.js` 6/6.
-
-
-### STRUCT-2 (Pass 3) — completed 2026-08-05
-
-- **STRUCT-2** — D1 implemented as decided: the `SH` proxy `set` trap now throws a `TypeError`
-  listing the known option keys when an unknown key is assigned (typo guard, e.g.
-  `SH.timout = 1`), instead of silently storing it in `defaultOptions` — where the `get` trap
-  would not read it back (`SH.foo = 1; SH.foo` === `undefined`). Reads of unknown keys are
-  unchanged (they fall through to the function target, usually `undefined`). Key-set alignment:
-  the hard-coded `defaultOptionKeys` list in `lib/SH.js` was replaced by `defaultOptionKeys`
-  exported from `lib/internal.js`, derived as `new Set(Object.keys(defaultOptions))` so the set
-  can never drift from the defaults again; `maxBuffer` and `detached` are now initialized in
-  `defaultOptions` (`DEFAULT_MAX_BUFFER` and `false`). This is behavior-neutral: `SHExecute`
-  already fell back to the same maxBuffer constant for unset/invalid values and truthy-checks
-  `detached`. `DEFAULT_MAX_BUFFER` moved above `defaultOptions` to satisfy TDZ.
-  Scenario 29 in `scenarios/sh.js` ('STRUCT-2: SH proxy throws on unknown option keys (D1)').
-
-Validation run: `node --check` on all changed files OK; `npm test` 30/30;
-`npm run types` exit 0; `node scenarios/parse_args.js` 6/6; manual smoke of the TypeError
-message and the initialized `SH.maxBuffer`/`SH.detached` readbacks OK.
-
-### STRUCT-4 (Pass 3) — completed 2026-08-05
-
-- **STRUCT-4** — `@ts-ignore` audit. Method: every suppression was re-verified against
-  `tsc --noEmit --checkJs` (stricter than the project gate — `tsc.json` covers `lib/**` only
-  and does not set `checkJs`, so the project's `npm run types` never exercised these).
-  - `parseArgs` (`lib/SH.js`): the return-site suppression moved to the declaration with the
-    prescribed typing — `const result = /** @type {ArgsObject} */ ({ _: [] });`. Deviation from
-    the sketched fix: the plain annotation form only relocates TS2322 to the declaration,
-    because `_: string[]` is fundamentally incompatible with the `string|true` index
-    signature — `_` is the intended exception, so one reasoned `@ts-ignore` remains at the
-    declaration. Also annotated `/** @type {string|true} */ let value;` (the `true` literal
-    otherwise widens to `boolean`). Net checkJs effect: 3 pre-existing parseArgs errors
-    removed, zero introduced.
-  - Removed as unneeded (no error even under `checkJs`): both `userIn` readline suppressions
-    and `cd`'s `process.chdir` suppression.
-  - Kept with reason comments: the two `options.stdio = stdio` suppressions in
-    `lib/SHExecute.js` (the `['pipe', 'pipe', 'pipe']` literal widens to `string[]`, which
-    `StdioOptions` rejects).
-  - Reason comments added to the 7 suppressions in `scenarios/test.js` /
-    `scenarios/asynctracker.js` (beyond the TODO's lib-only wording; those files are not
-    covered by `tsc.json` at all).
-
-Validation run: `node --check` on all changed files OK; `npm test` 30/30; `npm run types`
-exit 0 (regenerated types byte-identical); `node scenarios/parse_args.js` 6/6;
-`node scenarios/asynctracker.js` 6/6; `node scenarios/test.js` shows its 2 intentional
-self-test errors (verified pre-existing on HEAD); `tsc --noEmit --checkJs` delta vs the
-pre-audit baseline: 0 errors introduced, 3 removed.
-
-### STRUCT-3 (Pass 3) — completed 2026-08-05
-
-- **STRUCT-3** — Formatting unified with **no logic changes**:
-  - `.editorconfig` added: tab indentation as the project standard for JS (2-space for
-    JSON/MD/YAML; trailing-whitespace trimming, final newline, LF, UTF-8).
-  - `lib/SHExecute.js`: 217 lines converted 2-space → tabs (whole file).
-  - `lib/SH.js`: 41 space-indented lines (userIn/hasProp regions) converted to tabs; 6 lines
-    trailing-whitespace trimmed; semicolon drift fixed — 2 imports and 7 closing braces
-    (`defaultOptionHandler`, `within`, `readIn`, `retry`, `sleep`, `cd`, export list).
-  - No-logic-change proof: `git diff -w lib/` shows only the added semicolons;
-    `git diff -w lib/SHExecute.js` is empty. Multi-line template literals (whose inner
-    whitespace is significant) exist only in scenario files, which were deliberately left
-    as-is.
-  - Deviation note: `scenarios/*.js` indentation drift (a few 2-space and 4-space demo files)
-    was left untouched — outside the TODO's lib-focused scope, and several scenarios launch
-    interactive programs so they can't be regression-tested here. `.editorconfig` governs
-    future edits.
-
-Validation run: `node --check` on all changed files OK; `npm test` 30/30; `npm run types`
-exit 0 (types byte-identical); `node scenarios/parse_args.js` 6/6;
-`node scenarios/asynctracker.js` 6/6; `node scenarios/test.js` 2 intentional self-test errors.