procband 0.3.3 → 0.3.4

package/dist/index.d.mts

@@ -50,7 +50,10 @@ interface ProcessConfig {
   /**
    * Whether to spawn the child in a detached process group/session.
    *
-   * This is passed through to Node.js `spawn()` unchanged.
+   * This is passed through to Node.js `spawn()` unchanged. On Unix-like
+   * platforms, shutdown also signals the detached child's process group so
+   * same-group descendants are cleaned up even if they are no longer reachable
+   * through the child process tree.
    */
   detached?: boolean;
   /**
@@ -263,7 +266,8 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
    * Disable future restarts and terminate the active process tree.
    *
    * For supervised processes, `kill()` targets the current child process and
-   * any descendants it spawned instead of only the direct child.
+   * any descendants it spawned instead of only the direct child. Detached
+   * Unix-like children are also stopped by process group.
    * `kill(0)` preserves the normal `ChildProcess` existence-check behavior.
    */
   kill(signal?: KillSignal): boolean;

package/dist/index.mjs

@@ -290,18 +290,23 @@ function unregisterCleanupTarget(target) {
 	liveTargets.delete(target);
 	if (liveTargets.size === 0) uninstallParentCleanup();
 }
-function killTreeBestEffort(child, signal) {
+function killTreeBestEffort(child, signal, options = {}) {
+	if (options.detached) try {
+		killProcessGroup(child, signal);
+	} catch {}
 	try {
 		treeKillSync(child, signal);
 	} catch {}
 }
-async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
+async function stopChildTree(child, close, isClosed, signal, killAfterMs, options = {}) {
+	if (options.detached) killProcessGroup(child, signal);
 	try {
 		await treeKill(child, signal);
 	} catch (error) {
 		if (!isMissingProcessError(error)) throw error;
 	}
 	if (!await Promise.race([close.then(() => true), setTimeout$1(killAfterMs, false)]) && !isClosed()) {
+		if (options.detached) killProcessGroup(child, "SIGKILL");
 		try {
 			await treeKill(child, "SIGKILL");
 		} catch (error) {
@@ -310,6 +315,14 @@ async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
 		await close;
 	}
 }
+function killProcessGroup(child, signal) {
+	if (process.platform === "win32" || !child.pid) return;
+	try {
+		process.kill(-child.pid, signal);
+	} catch (error) {
+		if (!isMissingProcessError(error)) throw error;
+	}
+}
 function installParentCleanup() {
 	if (parentCleanupInstalled) return;
 	parentCleanupInstalled = true;
@@ -508,7 +521,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	cleanupFromExit() {
 		this.prepareShutdown();
 		const child = this.currentChild;
-		if (child) killTreeBestEffort(child, this.getParentCleanupSignal());
+		if (child) killTreeBestEffort(child, this.getParentCleanupSignal(), { detached: this.config.detached });
 	}
 	async cleanupFromSignal(signal) {
 		await this.beginShutdown(this.getParentCleanupSignal(signal), 1e3);
@@ -519,7 +532,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 			await this.finalPromise;
 			return;
 		}
-		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs);
+		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs, { detached: this.config.detached });
 	}
 	getParentCleanupSignal(fallback) {
 		return this.config.parentExitSignal ?? fallback;

package/docs/context.md

@@ -12,7 +12,7 @@ Supervision adds five behaviors on top of raw `spawn()`:
 - prefixed `stdout` and `stderr`
 - line-based matching for future output
 - optional restart policy with failure suppression
-- tree-aware shutdown for the child and its descendants
+- shutdown for the child and descendants, including detached Unix process groups
 - parent-exit propagation for unobserved terminal failures
 
 # When to Use
@@ -96,6 +96,9 @@ Supervision adds five behaviors on top of raw `spawn()`:
 # Recommended Patterns
 
 - Use `proc.kill()` for deliberate shutdown initiated by your own script.
+- Use `detached: true` when a child must run in its own process group/session.
+  On Unix-like platforms, `procband` uses that process group during shutdown in
+  addition to process-tree cleanup.
 - Reserve `parentExitSignal` for children that expect a specific signal from
   their supervisor during parent-driven cleanup.
 - Await `proc` or call `proc.wait()` when your script intends to own failure
@@ -130,12 +133,15 @@ Supervision adds five behaviors on top of raw `spawn()`:
 - The wrapper survives restarts, but inherited `pid`, `stdin`, `stdout`,
   `stderr`, and related `ChildProcess` fields always refer to the current active
   child attempt. `stdin` is `null` unless `ProcessConfig.stdin` is enabled.
-- `kill()` disables future restarts and kills the full process tree, except for
-  `kill(0)`, which only checks whether the current child attempt exists.
+- `kill()` disables future restarts and kills the full process tree. For
+  `detached: true` children on Unix-like platforms, shutdown also signals the
+  detached child's process group so same-group descendants are cleaned up even
+  when they are no longer reachable by parent PID. `kill(0)` only checks
+  whether the current child attempt exists.
 - Parent cleanup installs both `SIGINT` and `SIGTERM` handlers while any live
   supervised process exists. Set `ProcessConfig.parentExitSignal` to override
-  which signal is sent to the child tree during parent-driven cleanup. This
-  does not change the signal used by explicit `proc.kill()` calls.
+  which signal is sent during parent-driven cleanup. This does not change the
+  signal used by explicit `proc.kill()` calls.
 - `stderr` prefixes always use the reserved red, even when a custom process
   color is configured.
 - `ProcessConfig.name` is optional. When omitted, it falls back to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procband",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
   "author": "Alec Larson",