procband 0.3.5 → 0.3.6

package/README.md

@@ -1,38 +1,102 @@
 # procband
 
-## Purpose
+> Supervise subprocesses from TypeScript when a script needs prefixed output,
+> readiness matching, restart policy, and process-tree shutdown without becoming
+> a standalone process manager.
 
-`procband` supervises subprocesses from TypeScript. It prefixes child output,
-matches future log lines, waits for terminal exit, optionally restarts failed
-processes, tree-kills descendants during shutdown, and propagates unobserved
-terminal failures to the parent process.
+`procband` wraps one child process per `supervise()` call. It starts the child
+immediately, prefixes `stdout` and `stderr`, lets your script wait for future
+log lines, and resolves to a final `ProcessResult` when no more restart attempt
+will run.
 
-## Installation
+## Install
 
 ```sh
 pnpm add procband
 ```
 
-## Quick Example
+## First Process
+
+Use `waitFor()` when the next step depends on output that the child will print
+after supervision starts:
 
 ```ts
 import process from 'node:process'
 import { supervise } from 'procband'
 
 const proc = supervise({
+  name: 'worker',
   command: process.execPath,
   args: ['-e', 'console.log("ready")'],
 })
 
-await proc.waitFor('ready')
+const ready = await proc.waitFor('ready')
+console.log(`matched ${ready.line}`)
+
 const result = await proc
-console.log(result)
+console.log(result.exitCode)
+```
+
+The child output is written to the parent process with a `worker` prefix, the
+readiness wait resolves when a future line contains `ready`, and `await proc`
+returns the terminal result.
+
+## Choose the Failure Behavior
+
+By default, a failed terminal exit resolves to `ProcessResult`. Use this when a
+supervisor script needs to inspect the outcome:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const result = await supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+})
+
+if (result.exitCode !== 0) {
+  console.error(`job failed with ${result.exitCode}`)
+}
 ```
 
-## Documentation Map
+Use `expectSuccess()` for foreground command-runner steps where a failed exit
+should reject:
+
+```ts
+import { ProcessExitError, supervise } from 'procband'
+
+try {
+  await supervise({
+    name: 'db',
+    command: 'pnpm',
+    args: ['db', 'ensure'],
+  }).expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.args, error.exitCode)
+  }
+  throw error
+}
+```
+
+If your script never awaits the process or calls `wait()`, an unobserved failed
+terminal exit sets the parent `process.exitCode` and starts stopping other live
+`procband` processes in the same parent script.
+
+## Documentation
+
+Start with the page that matches the decision in front of you:
+
+| Page                                                      | Use it when                                                      |
+| --------------------------------------------------------- | ---------------------------------------------------------------- |
+| [Docs overview](docs/index.md)                            | You need the moving parts, boundaries, and next page to read.    |
+| [Readiness and matching](docs/guides/readiness.md)        | A script must wait for output or react to repeated log lines.    |
+| [Restart failed processes](docs/guides/restarts.md)       | A child can fail transiently and should be retried with limits.  |
+| [Foreground commands](docs/guides/foreground-commands.md) | A script step should reject when a command exits unsuccessfully. |
+| [Concepts and lifecycle](docs/context.md)                 | You need lifecycle, shutdown, error, and invariant details.      |
 
-- Concepts and lifecycle: [docs/context.md](docs/context.md)
-- Minimal usage example: [examples/basic-usage.ts](examples/basic-usage.ts)
-- Restart example: [examples/restart-on-failure.ts](examples/restart-on-failure.ts)
-- Sequencing example: [examples/sequenced-processes.ts](examples/sequenced-processes.ts)
-- Exact exported signatures: [dist/index.d.mts](dist/index.d.mts)
+Runnable examples live in [`examples/`](examples/). Exact public signatures are
+generated from the TypeScript source and published through
+[`dist/index.d.mts`](dist/index.d.mts).

package/dist/index.d.mts

@@ -62,6 +62,12 @@ interface ProcessConfig {
    * Defaults to `name`.
    */
   label?: string;
+  /**
+   * Whether child output should be prefixed with the process label.
+   *
+   * Defaults to `true`. Set to `false` for raw child output.
+   */
+  prefix?: boolean;
   /**
    * RGB color for this process's `stdout` prefix.
    *
@@ -221,6 +227,18 @@ interface ProcessResult {
    */
   restartSuppressed: boolean;
 }
+/**
+ * Options for `wait()`.
+ */
+interface WaitOptions {
+  /**
+   * Reject with `ProcessExitError` when the process exits unsuccessfully.
+   *
+   * Defaults to `false`, preserving procband's supervision-oriented behavior
+   * where terminal failures resolve to `ProcessResult`.
+   */
+  rejectOnFailure?: boolean;
+}
 /**
  * A supervised child-process handle.
  *
@@ -257,11 +275,16 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
   /**
    * Wait for the process to become terminal with no further restart pending.
    *
-   * Unlike many process helpers, this resolves for both success and failure.
-   * Inspect the returned `ProcessResult` instead of relying on promise
-   * rejection for non-zero exits.
+   * By default this resolves for both success and failure. Pass
+   * `rejectOnFailure: true` to reject failed exits with `ProcessExitError`.
+   */
+  wait(options?: WaitOptions): Promise<ProcessResult>;
+  /**
+   * Wait for the process to become terminal and reject if it fails.
+   *
+   * This is equivalent to `wait({ rejectOnFailure: true })`.
    */
-  wait(): Promise<ProcessResult>;
+  expectSuccess(): Promise<ProcessResult>;
   /**
    * Disable future restarts and terminate the active process tree.
    *
@@ -273,6 +296,21 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
   kill(signal?: KillSignal): boolean;
 }
 //#endregion
+//#region src/errors.d.ts
+/**
+ * Error thrown when a process was expected to exit successfully but did not.
+ */
+declare class ProcessExitError extends Error {
+  readonly config: ProcessConfig;
+  readonly result: ProcessResult;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly code: number | null;
+  readonly exitCode: number;
+  readonly signal: NodeJS.Signals | null;
+  constructor(config: ProcessConfig, result: ProcessResult);
+}
+//#endregion
 //#region src/process.d.ts
 /**
  * Start supervising a single subprocess.
@@ -303,4 +341,4 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
  */
 declare function supervise(config: ProcessConfig): ProcbandProcess;
 //#endregion
-export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, supervise };
+export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, ProcessExitError, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, type WaitOptions, supervise };

package/dist/index.mjs

@@ -5,6 +5,45 @@ import process from "node:process";
 import ansiStyles from "ansi-styles";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import treeKill, { treeKillSync } from "@alloc/tree-kill";
+//#region src/errors.ts
+/**
+* Error thrown when a process was expected to exit successfully but did not.
+*/
+var ProcessExitError = class extends Error {
+	config;
+	result;
+	command;
+	args;
+	code;
+	exitCode;
+	signal;
+	constructor(config, result) {
+		super(formatProcessExitMessage(config, result));
+		this.name = "ProcessExitError";
+		this.config = config;
+		this.result = result;
+		this.command = config.command;
+		this.args = [...config.args ?? []];
+		this.code = result.code;
+		this.exitCode = result.exitCode;
+		this.signal = result.signal;
+	}
+};
+function formatProcessExitMessage(config, result) {
+	const command = formatCommand(config);
+	const prefix = `Process "${result.name}" failed: ${command}`;
+	if (result.signal) return `${prefix} exited by signal ${result.signal} (exit code ${result.exitCode})`;
+	if (result.code != null) return `${prefix} exited with code ${result.code}`;
+	return `${prefix} exited unsuccessfully (exit code ${result.exitCode})`;
+}
+function formatCommand(config) {
+	return [config.command, ...config.args ?? []].map(formatCommandPart).join(" ");
+}
+function formatCommandPart(value) {
+	if (/^[\w./:=@%+,-]+$/.test(value)) return value;
+	return JSON.stringify(value);
+}
+//#endregion
 //#region src/colors.ts
 const prefixPalette = [
 	[
@@ -81,7 +120,8 @@ function validateProcessColor(color) {
 	if (red === stderrColor[0] && green === stderrColor[1] && blue === stderrColor[2]) throw new Error("ProcessConfig.color cannot use the reserved stderr color");
 }
 function writePrefixedLine(target, label, color, line, appendNewline) {
-	target.write(formatPrefix(label, color) + line + (appendNewline ? "\n" : ""));
+	const prefix = label == null ? "" : formatPrefix(label, color);
+	target.write(prefix + line + (appendNewline ? "\n" : ""));
 }
 function formatPrefix(label, color) {
 	return `${ansiStyles.color.ansi16m(...color)}[${label}]${ansiStyles.color.close} `;
@@ -400,6 +440,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	config;
 	name;
 	label;
+	prefix;
 	color;
 	matches;
 	restart;
@@ -422,6 +463,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		this.config = config;
 		this.name = name;
 		this.label = config.label ?? name;
+		this.prefix = config.name === "" ? false : config.prefix ?? true;
 		this.color = resolveProcessColor(config.color);
 		this.matches = new MatchRegistry(this.name);
 		this.restart = new RestartController(config.restart);
@@ -480,10 +522,14 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	waitFor(pattern, options) {
 		return this.matches.waitFor(pattern, options);
 	}
-	wait() {
+	wait(options) {
 		this.markTerminalResultObserved();
+		if (options?.rejectOnFailure) return this.finalPromise.then((result) => this.expectSuccessfulResult(result));
 		return this.finalPromise;
 	}
+	expectSuccess() {
+		return this.wait({ rejectOnFailure: true });
+	}
 	then(onfulfilled, onrejected) {
 		this.markTerminalResultObserved();
 		return this.finalPromise.then(onfulfilled, onrejected);
@@ -626,7 +672,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		buffer.text = text;
 	}
 	handleLine(stream, line, appendNewline) {
-		writePrefixedLine(stream === "stdout" ? process.stdout : process.stderr, this.label, stream === "stdout" ? this.color : stderrColor, line, appendNewline);
+		writePrefixedLine(stream === "stdout" ? process.stdout : process.stderr, this.prefix ? this.label : null, stream === "stdout" ? this.color : stderrColor, line, appendNewline);
 		this.matches.emit(stream, line);
 	}
 	async handleAttemptClose(code, signal) {
@@ -669,12 +715,16 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	}
 	closeMatches() {
 		const error = /* @__PURE__ */ new Error(`Process "${this.name}" exited before a matching line was observed`);
-		if (this.matches.hasPendingWait()) writePrefixedLine(process.stderr, this.label, stderrColor, error.message, true);
+		if (this.matches.hasPendingWait()) writePrefixedLine(process.stderr, this.prefix ? this.label : null, stderrColor, error.message, true);
 		this.matches.close(error);
 	}
 	markTerminalResultObserved() {
 		this.terminalResultObserved = true;
 	}
+	expectSuccessfulResult(result) {
+		if (isFailedResult(result)) throw new ProcessExitError(this.config, result);
+		return result;
+	}
 	shouldPropagateFailure(result) {
 		return result.exitCode !== 0 && !this.shutdownRequested && !this.terminalResultObserved;
 	}
@@ -734,7 +784,7 @@ let propagatedFailure = false;
 function validateProcessConfig(config) {
 	if (!config.command) throw new Error("ProcessConfig.command is required");
 	validateProcessColor(config.color);
-	const name = config.name || inferProcessName(config.command);
+	const name = config.name === void 0 || config.name === "" ? inferProcessName(config.command) : config.name;
 	if (!name) throw new Error("ProcessConfig.name is required when command does not match /[-\\w]+$/");
 	return name;
 }
@@ -746,6 +796,9 @@ function getResultExitCode(code, signal) {
 	if (signal) return 128 + (constants.signals[signal] ?? 0);
 	return 1;
 }
+function isFailedResult(result) {
+	return result.exitCode !== 0 || result.signal != null;
+}
 function propagateFailure(exitCode) {
 	if (propagatedFailure) return;
 	propagatedFailure = true;
@@ -756,4 +809,4 @@ function propagateFailure(exitCode) {
 	});
 }
 //#endregion
-export { supervise };
+export { ProcessExitError, supervise };

package/docs/context.md

@@ -1,184 +1,268 @@
-# Overview
-
-`procband` supervises one subprocess per `supervise()` call.
-
-The returned `ProcbandProcess` is both:
-
-- a `ChildProcess`-compatible handle for the current active child attempt
-- a thenable wrapper that resolves to a `ProcessResult` when supervision is done
-
-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
-- shutdown for the child and descendants, including detached Unix process groups
-- parent-exit propagation for unobserved terminal failures
-
-# When to Use
-
-- You are writing project-specific TypeScript scripts, not a CLI.
-- You need to wait for a subprocess to print a "ready" line.
-- You want readable prefixed logs from multiple long-lived child processes.
-- You need one shutdown API that kills descendant processes too.
-- You want automatic restart with a small built-in guard against tight failure
-  loops.
-
-# When Not to Use
-
-- You need a standalone process manager or service supervisor.
-- You need buffered log history or replay for late subscribers.
-- You need shell pipelines, shell parsing, or a command-line tool.
-- You want one API that supervises many processes at once. `procband` keeps the
-  unit of supervision to one process per call.
-
-# Core Abstractions
-
-- `ProcessConfig`
-  Declares one supervised subprocess plus its label, color, restart policy,
-  optional stdin behavior, optional detached spawn mode, optional
-  parent-exit signal override, and optional raw `stderr` tee.
-- `ProcbandProcess`
-  The live wrapper returned by `supervise()`. It is a `ChildProcess`-compatible
-  handle, a matching surface, a shutdown surface, and a thenable final result.
-- `MatchEvent`
-  A future matched line from `stdout` or `stderr`.
-- `RestartPolicy`
-  Rules for restart timing and failed-exit suppression.
-
-# Data Flow / Lifecycle
-
-1. `supervise(config)` spawns the first child process immediately.
-2. Child `stdout` and `stderr` are read as text and split into lines.
-3. Each line is prefixed and written to the parent `process.stdout` or
-   `process.stderr`.
-4. `stderr` can also be tee'd as raw bytes to `ProcessConfig.stderr`.
-5. `stdin` is disconnected by default. Set `ProcessConfig.stdin` to `true` for
-   a writable child stdin, or pass a readable stream to pipe input into the
-   child automatically.
-6. Future matching lines are delivered through `match()` callbacks or
-   `waitFor()`.
-7. When a child exits, `procband` either finalizes or starts a new attempt,
-   depending on the restart policy.
-8. A terminal failed exit that nobody observed through `await proc` or
-   `proc.wait()` sets `process.exitCode` and begins
-   stopping any other live `procband` processes in the same parent script.
-9. `await proc` or `await proc.wait()` resolves only after the process is
-   terminal and no further restart will happen.
-
-# Common Tasks -> Recommended APIs
-
-- Wait for one readiness line:
-  `proc.waitFor('ready')`
-- React to repeated matching output:
-  `proc.match(pattern, callback, options)`
-- Stop the process and its descendants:
-  `proc.kill()`
-- Inspect final exit state:
-  `await proc` or `await proc.wait()`
-- Take ownership of a process failure:
-  `await proc` or `await proc.wait()`
-- Let an unobserved terminal failure fail the parent script:
-  Do not call `wait()` or await the thenable result
-- Capture raw child `stderr` in a file or custom stream:
-  `ProcessConfig.stderr`
-- Write to child stdin manually:
-  `stdin: true`, then `proc.stdin?.write(...)`
-- Pipe a custom input stream into the child:
-  `stdin: readable`
-- Retry failed exits with sane defaults:
-  `restart: true`
-- Use explicit retry rules:
-  `restart: { when, delayMs, maxFailures, windowMs }`
-- Force a specific signal during parent shutdown:
-  `parentExitSignal: 'SIGHUP'`
-
-# 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
-  handling instead of inheriting procband's default parent-exit propagation.
-
-# Patterns to Avoid
-
-- Do not treat `parentExitSignal` as a replacement for the signal passed to
-  `proc.kill(signal)`. The former only changes parent-driven cleanup.
-- Do not expect `kill(0)` to stop supervision. `kill(0)` remains an existence
-  check for the current child attempt.
-- Do not expect historical log replay from `match()` or `waitFor()`. Matching
-  is future-only by design.
-
-# Invariants and Constraints
-
-- Matching is line-based and future-only.
-- String patterns use substring matching.
-- RegExp patterns run against the full observed line.
-- `match()` subscriptions do not interfere with each other.
-- `waitFor()` rejects if the process becomes terminal before a future match is
-  observed.
-- `await proc` resolves for both successful and failed exits. Inspect the
-  returned `ProcessResult`.
-- `ProcessResult.exitCode` exposes the shell-style exit status for the final
-  outcome, including signal exits.
-- Calling `proc.wait()` or awaiting the thenable process marks its terminal
-  result as observed and suppresses default parent-exit propagation.
-- An unobserved terminal failure sets `process.exitCode` to the first failing
-  process's `ProcessResult.exitCode` and starts stopping other live `procband`
-  processes in the same parent script.
-- 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. 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 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
-  trailing `/[-\w]+$/` match from `command`.
-
-# Error Model
-
-- `supervise()` throws synchronously for invalid config such as missing
-  `command`, a `command` that does not produce a fallback `name`, or an
-  invalid reserved color.
-- `waitFor()` rejects on timeout or terminal exit before a future match.
-- A thrown `match()` callback only unsubscribes that callback.
-- Errors from `ProcessConfig.stderr` stop teeing to that sink but do not stop
-  supervision.
-- Unobserved terminal failures do not reject promises. They set the parent
-  `process.exitCode` and start stopping sibling `procband` processes.
-- `kill()` emits `error` if tree-kill fails with a non-`ESRCH` error.
-
-# Terminology
-
-- Supervised process:
-  A `ProcbandProcess` wrapper plus its current child attempt.
-- Child attempt:
-  One concrete spawned process instance inside a supervision run.
-- Terminal:
-  No child is running and no restart will be started.
-- Restart suppression:
-  Automatic disabling of further restarts after too many failed exits inside the
-  configured window.
-- Match:
-  A future observed output line that satisfies a string or regex pattern.
-
-# Non-Goals
+# Concepts and Lifecycle
+
+> `procband` supervises one child process at a time; this page defines the
+> wrapper lifecycle, restart boundary, shutdown behavior, and failure model that
+> guide pages rely on.
+
+## Core Model
+
+Each `supervise(config)` call creates one supervised process. The returned
+`ProcbandProcess` is both:
+
+| Surface              | What it represents                                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Child-process handle | The current active child attempt. Inherited fields such as `pid`, `stdin`, `stdout`, and `stderr` update across restarts. |
+| Matching surface     | Future output lines observed by `match()` and `waitFor()`.                                                                |
+| Shutdown surface     | `kill()` disables future restarts and stops the current child process tree.                                               |
+| Thenable result      | `await proc` is equivalent to `await proc.wait()` and resolves to the terminal `ProcessResult`.                           |
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+
+await proc.waitFor('ready')
+const result = await proc
+```
+
+After the readiness line is observed, `result` is available only when the
+process is terminal and no restart delay or attempt remains.
+
+## Lifecycle
+
+1. `supervise(config)` validates the config and spawns the first child
+   immediately.
+2. Child `stdout` and `stderr` are decoded as UTF-8 text and split into lines.
+3. Each line is written to the parent `process.stdout` or `process.stderr` with
+   a process prefix unless `ProcessConfig.prefix` is `false`. `stderr` prefixes
+   always use the reserved red color.
+4. If `ProcessConfig.stderr` is provided, raw child `stderr` bytes are also
+   written to that sink.
+5. Matching subscribers receive future lines through `match()` callbacks or
+   `waitFor()` promises.
+6. When the child exits, `procband` either finalizes or schedules another child
+   attempt according to the restart policy.
+7. `await proc`, `await proc.wait()`, and `await proc.expectSuccess()` settle
+   only after the supervised process is terminal.
+
+Use this shape when one process must become ready before another starts:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => console.log("ready"), 20)'],
+})
+
+await api.waitFor('ready')
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'console.log("watching")'],
+})
+```
+
+The worker starts after the API prints a future line containing `ready`.
+
+## Output Prefixes
+
+By default, each child output line is written to the parent terminal with the
+process label:
+
+```ts
+supervise({
+  name: 'server',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+```
+
+Set `prefix: false` when a child should keep raw `stdout` and `stderr` output:
+
+```ts
+supervise({
+  name: 'server',
+  prefix: false,
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+```
+
+Disabling the prefix changes only parent-visible output and procband
+diagnostics. Matching events and final results still use the process `name`.
+
+## Matching
+
+Matching is line-based and future-only. A subscription sees lines emitted after
+the subscription is registered; it does not replay earlier output.
+
+| Pattern  | Behavior                                                                     |
+| -------- | ---------------------------------------------------------------------------- |
+| String   | Matches when the observed line includes the string.                          |
+| `RegExp` | Runs against the full observed line. `lastIndex` is reset before each match. |
+
+Use `waitFor()` for one required line:
+
+```ts
+const event = await proc.waitFor(/^ready$/, {
+  stream: 'stdout',
+  timeoutMs: 5000,
+})
+
+console.log(event.process, event.line)
+```
+
+Use `match()` for repeated lines:
+
+```ts
+const unsubscribe = proc.match(
+  /^attempt \d+$/,
+  (event) => {
+    console.log(`observed ${event.line}`)
+  },
+  { stream: 'stdout' },
+)
+
+unsubscribe()
+```
+
+`waitFor()` rejects when its timeout elapses or the process becomes terminal
+before a matching future line appears. If a `match()` callback throws, only that
+subscription is removed.
+
+## Restarts
+
+`restart: true` uses the built-in policy:
+
+| Field         | Default        | Meaning                                                  |
+| ------------- | -------------- | -------------------------------------------------------- |
+| `when`        | `'on-failure'` | Restart only non-zero exits or signal exits.             |
+| `delayMs`     | `1000`         | Wait this long before the next attempt.                  |
+| `maxFailures` | `3`            | Suppress restart after more than this many failed exits. |
+| `windowMs`    | `30000`        | Count failed exits inside this rolling window.           |
+
+Pass an explicit policy when the defaults are too slow or too permissive:
+
+```ts
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: {
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+
+const result = await proc
+console.log(result.restarts, result.restartSuppressed)
+```
+
+If the child keeps failing inside the configured window, `restartSuppressed`
+becomes `true` and the final failed result is returned.
+
+## Shutdown
+
+Use `proc.kill()` for deliberate shutdown from your own script:
+
+```ts
+const stopped = proc.kill('SIGTERM')
+```
+
+`kill()` disables future restarts and stops the active child process tree. For
+`detached: true` children on Unix-like platforms, shutdown also signals the
+detached child process group so same-group descendants are cleaned up even when
+they are no longer reachable by parent PID.
+
+> [!NOTE]
+> `kill(0)` keeps the normal Node.js existence-check behavior. It does not stop
+> supervision or disable restarts.
+
+Parent cleanup installs `SIGINT` and `SIGTERM` handlers while live supervised
+processes exist. Set `parentExitSignal` only when children require a specific
+signal during parent-driven cleanup:
+
+```ts
+supervise({
+  name: 'server',
+  command: process.execPath,
+  args: ['server.mjs'],
+  parentExitSignal: 'SIGHUP',
+})
+```
+
+`parentExitSignal` does not change the signal used by explicit `proc.kill()`
+calls.
+
+## Failure Model
+
+`procband` separates terminal process failure from promise rejection:
+
+| API                                    | Failed terminal exit                                                                |
+| -------------------------------------- | ----------------------------------------------------------------------------------- |
+| `await proc`                           | Resolves to `ProcessResult`.                                                        |
+| `proc.wait()`                          | Resolves to `ProcessResult`.                                                        |
+| `proc.wait({ rejectOnFailure: true })` | Rejects with `ProcessExitError`.                                                    |
+| `proc.expectSuccess()`                 | Rejects with `ProcessExitError`.                                                    |
+| Unobserved process                     | Sets parent `process.exitCode` and starts stopping other live supervised processes. |
+
+`ProcessExitError` includes the original config, final result, command, args,
+exit code, and signal:
+
+```ts
+import { ProcessExitError } from 'procband'
+
+try {
+  await proc.expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.exitCode, error.signal)
+  }
+  throw error
+}
+```
+
+## Configuration Boundaries
+
+| Field      | Boundary                                                                                                         |
+| ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `command`  | Required shell-free executable or command name passed to `spawn()`.                                              |
+| `name`     | Optional stable process identifier. Defaults to the trailing `/[-\w]+$/` match from `command`.                   |
+| `label`    | Optional human-facing output prefix. Defaults to `name`.                                                         |
+| `prefix`   | Defaults to `true`. Set to `false` to write output and diagnostics without the process label prefix.             |
+| `stdin`    | Defaults to disconnected. Use `true` for writable `proc.stdin`, or pass a readable stream to pipe automatically. |
+| `stderr`   | Optional extra sink for raw child `stderr`; prefixed parent `stderr` output still happens.                       |
+| `detached` | Passed through to `spawn()` and used during shutdown on Unix-like platforms.                                     |
+| `color`    | Optional RGB prefix color for `stdout`; reserved `stderr` red cannot be used.                                    |
+
+Invalid config, such as a missing `command`, a command without an inferable
+fallback `name`, or a reserved color, throws synchronously from `supervise()`.
+
+## Terminology
+
+| Term                | Meaning                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| Supervised process  | A `ProcbandProcess` wrapper plus its current child attempt.                                       |
+| Child attempt       | One concrete spawned process instance inside a supervision run.                                   |
+| Terminal            | No child is running and no restart will be started.                                               |
+| Restart suppression | Automatic disabling of further restarts after too many failed exits inside the configured window. |
+| Match               | A future observed output line that satisfies a string or regex pattern.                           |
+
+## Non-Goals
 
 - A standalone CLI
 - Historical log replay
 - Multi-process orchestration in one top-level API
 - Shell command parsing
-- Full service-management features such as persistence, cron scheduling, or host
+- Service-management features such as persistence, cron scheduling, or host
   restarts

package/docs/guides/foreground-commands.md

@@ -0,0 +1,80 @@
+# Foreground Commands
+
+> Use `expectSuccess()` when a supervised child process represents a script step
+> that must succeed before the parent script can continue.
+
+`procband` normally resolves failed exits to `ProcessResult` because background
+supervision often needs to inspect failures instead of throwing immediately.
+Foreground command-runner steps usually want the opposite behavior.
+
+## Reject Failed Exits
+
+Use `expectSuccess()` when a non-zero exit or signal exit should reject:
+
+```ts
+import process from 'node:process'
+import { ProcessExitError, supervise } from 'procband'
+
+try {
+  await supervise({
+    name: 'db',
+    command: 'pnpm',
+    args: ['db', 'ensure'],
+  }).expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.args, error.exitCode)
+  }
+  throw error
+}
+```
+
+When the command exits successfully, the promise resolves to `ProcessResult`.
+When it fails, `ProcessExitError` exposes the command, args, exit code, signal,
+original config, and terminal result.
+
+## Use `wait()` When the Choice Is Dynamic
+
+`expectSuccess()` is equivalent to `wait({ rejectOnFailure: true })`. Use
+`wait()` when a caller decides the behavior:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'check',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+})
+
+const result = await proc.wait({ rejectOnFailure: shouldThrow })
+```
+
+If `shouldThrow` is `false`, the failed exit resolves to `ProcessResult`. If it
+is `true`, the same exit rejects with `ProcessExitError`.
+
+## Let Background Failures Propagate
+
+For background processes that should fail the parent script when nobody handles
+their result, leave the process unobserved:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => process.exit(1), 60)'],
+})
+```
+
+If this process reaches a failed terminal state and no code has awaited it or
+called `wait()`, `procband` sets the parent `process.exitCode` and starts
+stopping other live `procband` processes in the same parent script.
+
+> [!IMPORTANT]
+> Awaiting `proc` or calling `proc.wait()` marks the terminal result as
+> observed. Once observed, default parent-exit propagation is suppressed for
+> that process.

package/docs/guides/readiness.md

@@ -0,0 +1,104 @@
+# Readiness and Matching
+
+> Use future line matching when a parent script must wait for a child process to
+> announce readiness or react to repeated output without buffering log history.
+
+Matching starts when you call `waitFor()` or `match()`. Earlier output is not
+replayed, so create the supervised process and register the wait before the line
+you need can be missed.
+
+## Wait for One Line
+
+Use `waitFor()` when the next step cannot start until the child prints a known
+line:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: [
+    '-e',
+    [
+      'console.log("booting")',
+      'setTimeout(() => console.log("ready"), 20)',
+      'setInterval(() => {}, 1000)',
+    ].join(';'),
+  ],
+})
+
+const event = await api.waitFor('ready', {
+  stream: 'stdout',
+  timeoutMs: 5000,
+})
+
+console.log(`api is ${event.line}`)
+```
+
+The wait resolves with the first future `stdout` line that contains `ready`.
+When `timeoutMs` elapses first, or the process exits before a matching line is
+observed, the wait rejects.
+
+## Match Repeated Lines
+
+Use `match()` when the child may print the same kind of line many times:
+
+```ts
+const unsubscribe = api.match(
+  /^warn:/,
+  (event) => {
+    console.log(`observed ${event.stream}: ${event.line}`)
+  },
+  { stream: 'stderr' },
+)
+
+// Later, when this script no longer needs warning callbacks:
+unsubscribe()
+```
+
+Each subscription is independent. If one callback throws, that subscription is
+removed and other subscriptions keep running.
+
+## Choose a Pattern
+
+| Pattern     | Best for                             | Result detail                                      |
+| ----------- | ------------------------------------ | -------------------------------------------------- |
+| `'ready'`   | Simple substring checks.             | `event.match` is `null`.                           |
+| `/^ready$/` | Exact line shape or captured values. | `event.match` contains the `RegExp.exec()` result. |
+
+```ts
+const event = await api.waitFor(/^listening on (\d+)$/)
+const port = Number(event.match?.[1])
+```
+
+The regular expression runs against the full observed line without the trailing
+newline.
+
+## Start Another Process After Readiness
+
+This pattern keeps sequencing explicit: wait for the first process, then start
+the dependent process.
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => console.log("ready"), 20)'],
+})
+
+await api.waitFor('ready')
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'console.log("watching")'],
+})
+```
+
+After the API prints `ready`, the worker starts and its output is prefixed
+separately.

package/docs/guides/restarts.md

@@ -0,0 +1,115 @@
+# Restart Failed Processes
+
+> Add a restart policy when a child process may fail transiently and the parent
+> script should retry before treating the supervision run as terminal.
+
+Restarts are disabled by default. Enable them per process with `restart: true`
+or an explicit `RestartPolicy`.
+
+## Use the Built-In Policy
+
+Use `restart: true` when the defaults are acceptable:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: true,
+})
+
+const result = await proc
+console.log(result.restarts, result.restartSuppressed)
+```
+
+The default policy restarts failed exits after `1000` milliseconds and suppresses
+restart after more than `3` failed exits inside `30000` milliseconds.
+
+## Set an Explicit Policy
+
+Use an explicit policy when tests, examples, or short-lived scripts need faster
+feedback:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: {
+    when: 'on-failure',
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+```
+
+With this policy, failed attempts are retried after `25` milliseconds. Once more
+than `5` failures occur inside `1000` milliseconds, `procband` stops retrying
+and resolves the terminal result with `restartSuppressed: true`.
+
+## Wait for a Later Attempt
+
+`waitFor()` watches future output across restart attempts, so it can wait for a
+line that appears only after earlier attempts fail:
+
+```ts
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { supervise } from 'procband'
+
+const stateDir = mkdtempSync(join(tmpdir(), 'procband-example-'))
+const attemptFile = join(stateDir, 'attempt.txt')
+writeFileSync(attemptFile, '0')
+
+const script = [
+  'const fs = await import("node:fs")',
+  'const file = process.argv[1]',
+  'let attempt = Number(fs.readFileSync(file, "utf8"))',
+  'attempt += 1',
+  'fs.writeFileSync(file, String(attempt))',
+  'console.log(`attempt ${attempt}`)',
+  'if (attempt < 3) process.exit(1)',
+  'console.log("ready")',
+].join(';')
+
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', script, attemptFile],
+  restart: {
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+
+proc.match(/^attempt \d+$/, (event) => {
+  console.log(`observed ${event.line}`)
+})
+
+await proc.waitFor('ready')
+const result = await proc
+```
+
+The first two attempts can exit unsuccessfully, the third attempt can print
+`ready`, and the final result includes the number of restart attempts that were
+started.
+
+## Pick `when` Deliberately
+
+| `when`         | Restarts after                   | Use it when                                                                          |
+| -------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
+| `'on-failure'` | Non-zero exits and signal exits. | A clean exit means the work is done.                                                 |
+| `'on-exit'`    | Any exit.                        | The child is expected to be long-lived and should be relaunched even after code `0`. |
+
+`proc.kill()` disables future restarts before stopping the active process tree,
+so deliberate shutdown does not start another attempt.

package/docs/index.md

@@ -0,0 +1,61 @@
+# Documentation Overview
+
+> Choose the right `procband` behavior before reaching for an API: readiness
+> matching, failure observation, restart policy, and shutdown each change how a
+> script should supervise its child process.
+
+`procband` is for TypeScript scripts that need to run child processes with a
+small amount of supervision. It is not a daemon, service manager, CLI runner, or
+multi-process orchestrator.
+
+## What It Adds
+
+Each `supervise()` call wraps one child process and adds five behaviors on top
+of Node.js `spawn()`:
+
+| Behavior                       | Use it when                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| Optional prefixed output       | Multiple child processes write to the same parent terminal.                |
+| Future line matching           | The parent script must wait for a readiness line or react to logs.         |
+| Optional restarts              | A transient failure should start another child attempt.                    |
+| Process-tree shutdown          | Deliberate cleanup should stop descendants as well as the direct child.    |
+| Unobserved failure propagation | A background failure should fail the parent script when nobody awaited it. |
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+
+await proc.waitFor('ready')
+```
+
+After `supervise()` runs, the child has already started and future output can be
+matched.
+
+## First Decisions
+
+| Decision         | Default                                       | Change it when                                                             |
+| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
+| Process identity | `name` is inferred from `command`.            | The command path does not end in `/[-\w]+$/`, or logs need a stable label. |
+| Output prefix    | Child output is labeled.                      | Pass `prefix: false` when the child should write raw output.               |
+| Failure handling | Awaiting resolves to `ProcessResult`.         | Use `expectSuccess()` for command-runner steps that should reject.         |
+| Matching scope   | `waitFor()` and `match()` watch both streams. | Pass `{ stream: 'stdout' }` or `{ stream: 'stderr' }` to narrow matching.  |
+| Restart behavior | No restart.                                   | Pass `restart: true` or a policy for transient child failures.             |
+| Stdin            | Disconnected.                                 | Pass `stdin: true` or a readable stream when the child needs input.        |
+
+## Where to Go Next
+
+| Page                                                 | Reader job                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| [Readiness and matching](guides/readiness.md)        | Wait for future output or subscribe to repeated matching lines.     |
+| [Restart failed processes](guides/restarts.md)       | Configure retries with a failure-suppression guard.                 |
+| [Foreground commands](guides/foreground-commands.md) | Make a supervised command reject on failed exit.                    |
+| [Concepts and lifecycle](context.md)                 | Understand terminal state, shutdown, config boundaries, and errors. |
+
+Runnable scripts in [`../examples/`](../examples/) cover the same workflows with
+project-realistic child processes that can be checked by `pnpm docs:check`.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "procband",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
+  "packageManager": "pnpm@11.5.1",
   "license": "MIT",
   "author": "Alec Larson",
   "repository": {
@@ -18,8 +19,19 @@
     "types": "./dist/index.d.mts",
     "default": "./dist/index.mjs"
   },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "docs:check": "pnpm build && tsc -p examples --noEmit && node examples/basic-usage.ts && node examples/restart-on-failure.ts",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "test": "vitest",
+    "prepublishOnly": "pnpm build"
+  },
   "devDependencies": {
     "@types/node": "^25.5.2",
+    "lildocs": "^0.1.11",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.58.0",
     "tsdown": "^0.21.7",
@@ -29,14 +41,5 @@
   "dependencies": {
     "@alloc/tree-kill": "^1.4.0",
     "ansi-styles": "^6.2.3"
-  },
-  "scripts": {
-    "dev": "tsdown --sourcemap --watch",
-    "build": "tsdown",
-    "docs:check": "pnpm build && tsc -p examples --noEmit && node examples/basic-usage.ts && node examples/restart-on-failure.ts",
-    "format": "oxfmt .",
-    "lint": "oxlint src",
-    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
-    "test": "vitest"
   }
-}
+}