@orkestrel/process 0.0.10 → 0.0.11

package/README.md

@@ -1,26 +1,15 @@
 # @orkestrel/process
 
-A typed **child-process toolkit** in tiers. `Process` supervises one
-child: stdout is framed into lines under a bounded backlog, stderr is forwarded
-live and kept as a byte-bounded tail, stdin is a writable channel, and
-termination is bounded and reports whether the real exit arrived — `SIGTERM` then
-`SIGKILL` after a grace window on a POSIX host, a whole-tree kill on Windows.
-`Session` supervises the same child as raw bytes instead: one owned
-`Uint8Array` per stdout chunk, an `end` that closes stdin without terminating
-anything, and the child's own `ending` beside the terminal `exit`.
-`execute` and `executeSync` buffer a child to completion and settle with an
-`ExecuteResult` carrying the captured output, the exit, and `failed` /
-`expired` / `aborted` / `truncated`, rejecting with a `ProcessError` by default
-or resolving the result when you pass `strict: false`. `ProcessManager` is a
-keyed registry of live children: `launch` spawns and registers by id, a settled
-child evicts itself with no polling, and `stop` terminates one id, a list, or
-every child. `Process`, `Session`, and `ProcessManager` expose typed `emitter`
-properties.
-`Process`, `launch`, and `execute` take an `AbortSignal` that terminates the
-child; `executeSync` and `detach` take none. No spawn uses a shell, so a
-metacharacter in an argument is data rather than syntax. The contracts are
-host-independent and ship from `@orkestrel/process`; the Node engine ships from
-`@orkestrel/process/server`. Part of the `@orkestrel` line.
+> A typed child-process toolkit in tiers: the supervised `Process` with framed stdout lines and a
+> writable stdin channel, the byte-oriented `Session`, the buffered `execute` and `executeSync`
+> runs, the fire-and-forget `detach`, and the keyed `ProcessManager` registry, none of them spawning
+> through a shell.
+
+Spawn a supervised child with the `createProcess` function, read the lines it frames, and call
+`stop()` to end it on a bounded window. Reach for `execute` where you want the captured output and
+the exit in one call, and for `ProcessManager` where you supervise several children by id. The
+contracts ship from `@orkestrel/process` and the Node engine from `@orkestrel/process/server`. Part
+of the `@orkestrel` line.
 
 ## Install
 

package/dist/src/core/index.cjs

@@ -1,13 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
 //#region src/core/constants.ts
-/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
-/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */
+/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */
 var PROCESS_CONFIRMATION = 5e3;
 /**
-* Names the default window in milliseconds the package waits for the child's read ends to close after
-* the child's native exit or after a termination this package initiated, before cutting them off.
+* Names the default window, 1000 ms, the package waits for the child's read ends to close after the
+* child's native exit or after a termination this package initiated, before cutting them off.
 *
 * @remarks
 * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
@@ -21,17 +21,20 @@ var PROCESS_CONFIRMATION = 5e3;
 * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.
 */
 var PROCESS_DRAIN = 1e3;
-/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */
 var PROCESS_EVIDENCE = 2048;
-/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */
 var PROCESS_BACKLOG = 10485760;
-/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */
 var PROCESS_OUTPUT = 10485760;
-/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */
+/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */
 var PROCESS_TIMER = 2147483647;
-/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */
 var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
-/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+/**
+* Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:
+* `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+*/
 var PROCESS_ERROR_CODES = Object.freeze([
 	"spawn",
 	"timeout",
@@ -105,7 +108,7 @@ function isProcessError(value) {
 	});
 }
 /**
-* Creates the failure raised when a manager launch reuses a live id.
+* Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.
 *
 * @param id - The id already occupied by a live child
 * @returns A typed duplicate-id failure
@@ -117,7 +120,8 @@ function createDuplicateError(id) {
 	});
 }
 /**
-* Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+* Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is
+* being destroyed.
 *
 * @param id - The id the refused launch asked for
 * @returns A typed protocol failure
@@ -129,7 +133,8 @@ function createProtocolError(id) {
 	});
 }
 /**
-* Creates the failure raised when a public input is refused before anything is spawned.
+* Creates the `invalid`-coded failure raised when a public input is refused before anything is
+* spawned.
 *
 * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
 * @param value - The rejected value, carried as `context.value`

package/dist/src/core/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * Names the default window in milliseconds the package waits for the child's read ends to close after\n * the child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/**\n * Represents a child-process failure with a stable machine-readable category.\n *\n * @example\n * ```ts\n * const error = new ProcessError('git status refused', {\n * \tcode: 'invalid',\n * \tcontext: { command: 'git status' },\n * })\n * error.code // 'invalid'\n * ```\n */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** Carries the buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Creates a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True if the value is a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a launch is attempted on a registry that is being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a public input is refused before anything is spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;AAG/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;;;;;;;;;;;;ACzBV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,EAAA,GAAC,oBAAA,QAAA,CAAQ,KAAK,GAAG,OAAO;CAC5B,QAAA,GAAO,oBAAA,MAAA,OAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * Names the default window, 1000 ms, the package waits for the child's read ends to close after the\n * child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/**\n * Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:\n * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.\n */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/**\n * Represents a child-process failure with a stable machine-readable category.\n *\n * @example\n * ```ts\n * const error = new ProcessError('git status refused', {\n * \tcode: 'invalid',\n * \tcontext: { command: 'git status' },\n * })\n * error.code // 'invalid'\n * ```\n */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** Carries the buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Creates a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True if the value is a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is\n * being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the `invalid`-coded failure raised when a public input is refused before anything is\n * spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;;;;AAM/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;;;;;;;;;;;;AC5BV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,EAAA,GAAC,oBAAA,QAAA,CAAQ,KAAK,GAAG,OAAO;CAC5B,QAAA,GAAO,oBAAA,MAAA,OAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;AASA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;;AAeA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}

package/dist/src/core/index.d.cts

@@ -1,9 +1,9 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * Creates the failure raised when a manager launch reuses a live id.
+ * Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.
  *
  * @param id - The id already occupied by a live child
  * @returns A typed duplicate-id failure
@@ -25,7 +25,8 @@ export declare function createDuplicateError(id: string): ProcessError;
 export declare function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError;
 
 /**
- * Creates the failure raised when a public input is refused before anything is spawned.
+ * Creates the `invalid`-coded failure raised when a public input is refused before anything is
+ * spawned.
  *
  * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
  * @param value - The rejected value, carried as `context.value`
@@ -39,7 +40,8 @@ export declare function createExecuteError(result: ExecuteResult, cause?: unknow
 export declare function createInvalidError(subject: string, value: unknown): ProcessError;
 
 /**
- * Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+ * Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is
+ * being destroyed.
  *
  * @param id - The id the refused launch asked for
  * @returns A typed protocol failure
@@ -219,15 +221,15 @@ export declare interface ExecuteSyncOptions {
  */
 export declare function isProcessError(value: unknown): value is ProcessError;
 
-/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */
 export declare const PROCESS_BACKLOG = 10485760;
 
-/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */
+/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */
 export declare const PROCESS_CONFIRMATION = 5000;
 
 /**
- * Names the default window in milliseconds the package waits for the child's read ends to close after
- * the child's native exit or after a termination this package initiated, before cutting them off.
+ * Names the default window, 1000 ms, the package waits for the child's read ends to close after the
+ * child's native exit or after a termination this package initiated, before cutting them off.
  *
  * @remarks
  * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
@@ -242,22 +244,25 @@ export declare const PROCESS_CONFIRMATION = 5000;
  */
 export declare const PROCESS_DRAIN = 1000;
 
-/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+/**
+ * Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:
+ * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+ */
 export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "input", "duplicate", "protocol", "invalid"];
 
-/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
-/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */
 export declare const PROCESS_GRACE = 5000;
 
-/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */
 export declare const PROCESS_OUTPUT = 10485760;
 
-/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */
 export declare const PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
 
-/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */
+/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */
 export declare const PROCESS_TIMER = 2147483647;
 
 /**
@@ -332,7 +337,10 @@ export declare class ProcessError extends Error {
     constructor(message: string, options: ProcessErrorOptions);
 }
 
-/** Names the machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}. */
+/**
+ * Names the machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}:
+ * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+ */
 export declare type ProcessErrorCode = (typeof PROCESS_ERROR_CODES)[number];
 
 /** Represents structured context carried by a {@link ProcessError}. */
@@ -625,7 +633,8 @@ export declare interface ProcessManagerInterface {
      */
     launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
-     * Terminates the named children and awaits their exit.
+     * Terminates the named children, or every live child when a call names none, and awaits their
+     * exit.
      *
      * @param ids - The registry keys to stop
      * @returns True if every named child was live and its exit was confirmed; false otherwise

package/dist/src/core/index.d.ts

@@ -1,9 +1,9 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * Creates the failure raised when a manager launch reuses a live id.
+ * Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.
  *
  * @param id - The id already occupied by a live child
  * @returns A typed duplicate-id failure
@@ -25,7 +25,8 @@ export declare function createDuplicateError(id: string): ProcessError;
 export declare function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError;
 
 /**
- * Creates the failure raised when a public input is refused before anything is spawned.
+ * Creates the `invalid`-coded failure raised when a public input is refused before anything is
+ * spawned.
  *
  * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
  * @param value - The rejected value, carried as `context.value`
@@ -39,7 +40,8 @@ export declare function createExecuteError(result: ExecuteResult, cause?: unknow
 export declare function createInvalidError(subject: string, value: unknown): ProcessError;
 
 /**
- * Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+ * Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is
+ * being destroyed.
  *
  * @param id - The id the refused launch asked for
  * @returns A typed protocol failure
@@ -219,15 +221,15 @@ export declare interface ExecuteSyncOptions {
  */
 export declare function isProcessError(value: unknown): value is ProcessError;
 
-/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */
 export declare const PROCESS_BACKLOG = 10485760;
 
-/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */
+/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */
 export declare const PROCESS_CONFIRMATION = 5000;
 
 /**
- * Names the default window in milliseconds the package waits for the child's read ends to close after
- * the child's native exit or after a termination this package initiated, before cutting them off.
+ * Names the default window, 1000 ms, the package waits for the child's read ends to close after the
+ * child's native exit or after a termination this package initiated, before cutting them off.
  *
  * @remarks
  * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
@@ -242,22 +244,25 @@ export declare const PROCESS_CONFIRMATION = 5000;
  */
 export declare const PROCESS_DRAIN = 1000;
 
-/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+/**
+ * Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:
+ * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+ */
 export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "input", "duplicate", "protocol", "invalid"];
 
-/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
-/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */
 export declare const PROCESS_GRACE = 5000;
 
-/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */
 export declare const PROCESS_OUTPUT = 10485760;
 
-/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */
 export declare const PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
 
-/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */
+/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */
 export declare const PROCESS_TIMER = 2147483647;
 
 /**
@@ -332,7 +337,10 @@ export declare class ProcessError extends Error {
     constructor(message: string, options: ProcessErrorOptions);
 }
 
-/** Names the machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}. */
+/**
+ * Names the machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}:
+ * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+ */
 export declare type ProcessErrorCode = (typeof PROCESS_ERROR_CODES)[number];
 
 /** Represents structured context carried by a {@link ProcessError}. */
@@ -625,7 +633,8 @@ export declare interface ProcessManagerInterface {
      */
     launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
-     * Terminates the named children and awaits their exit.
+     * Terminates the named children, or every live child when a call names none, and awaits their
+     * exit.
      *
      * @param ids - The registry keys to stop
      * @returns True if every named child was live and its exit was confirmed; false otherwise

package/dist/src/core/index.js

@@ -1,12 +1,12 @@
 import { holds, isError } from "@orkestrel/contract";
 //#region src/core/constants.ts
-/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
-/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */
+/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */
 var PROCESS_CONFIRMATION = 5e3;
 /**
-* Names the default window in milliseconds the package waits for the child's read ends to close after
-* the child's native exit or after a termination this package initiated, before cutting them off.
+* Names the default window, 1000 ms, the package waits for the child's read ends to close after the
+* child's native exit or after a termination this package initiated, before cutting them off.
 *
 * @remarks
 * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
@@ -20,17 +20,20 @@ var PROCESS_CONFIRMATION = 5e3;
 * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.
 */
 var PROCESS_DRAIN = 1e3;
-/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */
 var PROCESS_EVIDENCE = 2048;
-/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */
 var PROCESS_BACKLOG = 10485760;
-/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */
 var PROCESS_OUTPUT = 10485760;
-/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */
+/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */
 var PROCESS_TIMER = 2147483647;
-/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */
 var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
-/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+/**
+* Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:
+* `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.
+*/
 var PROCESS_ERROR_CODES = Object.freeze([
 	"spawn",
 	"timeout",
@@ -104,7 +107,7 @@ function isProcessError(value) {
 	});
 }
 /**
-* Creates the failure raised when a manager launch reuses a live id.
+* Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.
 *
 * @param id - The id already occupied by a live child
 * @returns A typed duplicate-id failure
@@ -116,7 +119,8 @@ function createDuplicateError(id) {
 	});
 }
 /**
-* Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+* Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is
+* being destroyed.
 *
 * @param id - The id the refused launch asked for
 * @returns A typed protocol failure
@@ -128,7 +132,8 @@ function createProtocolError(id) {
 	});
 }
 /**
-* Creates the failure raised when a public input is refused before anything is spawned.
+* Creates the `invalid`-coded failure raised when a public input is refused before anything is
+* spawned.
 *
 * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
 * @param value - The rejected value, carried as `context.value`

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * Names the default window in milliseconds the package waits for the child's read ends to close after\n * the child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/**\n * Represents a child-process failure with a stable machine-readable category.\n *\n * @example\n * ```ts\n * const error = new ProcessError('git status refused', {\n * \tcode: 'invalid',\n * \tcontext: { command: 'git status' },\n * })\n * error.code // 'invalid'\n * ```\n */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** Carries the buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Creates a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True if the value is a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a launch is attempted on a registry that is being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a public input is refused before anything is spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;AAG/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;;;;;;;;;;;;ACzBV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC5B,OAAO,YAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * Names the default window, 1000 ms, the package waits for the child's read ends to close after the\n * child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** Names the default maximum retained stderr tail, 2048 bytes, for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** Names the default soft high-water mark, 10485760 bytes, for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/**\n * Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order:\n * `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`.\n */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/**\n * Represents a child-process failure with a stable machine-readable category.\n *\n * @example\n * ```ts\n * const error = new ProcessError('git status refused', {\n * \tcode: 'invalid',\n * \tcontext: { command: 'git status' },\n * })\n * error.code // 'invalid'\n * ```\n */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** Carries the buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Creates a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True if the value is a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the `duplicate`-coded failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is\n * being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the `invalid`-coded failure raised when a public input is refused before anything is\n * spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;;;;AAM/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;;;;;;;;;;;;AC5BV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC5B,OAAO,YAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;AASA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;;AAeA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}

package/dist/src/server/index.cjs

@@ -307,7 +307,8 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
 	return Object.freeze(targets);
 }
 /**
-* Resolves a command file to the executable path the host would launch.
+* Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+* host, which performs its own lookup.
 *
 * @param file - The command executable name or path
 * @param options - The directory searched first and the child's effective environment
@@ -1446,7 +1447,8 @@ var Supervisor = class {
 //#endregion
 //#region src/server/processes/Process.ts
 /**
-* Supervises one child while keeping every observation channel aligned at termination.
+* Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+* every observation channel aligned at termination.
 *
 * @remarks
 * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -1735,7 +1737,8 @@ var Process = class {
 //#endregion
 //#region src/server/processes/ProcessManager.ts
 /**
-* Represents a keyed registry of live supervised child processes.
+* Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+* every live child on teardown.
 *
 * @remarks
 * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -2081,27 +2084,37 @@ var Session = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates one supervised child process.
+* Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+* holds the published contract rather than the `Process` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link ProcessInterface}
 *
-* @example
+* @example Supervise a child and read its lines
 * ```ts
 * import { createProcess } from '@orkestrel/process/server'
 *
 * const child = createProcess({
-* 	command: { file: 'node', arguments: ['--version'] },
+* 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
 * 	workspace: process.cwd(),
-* 	grace: 5000,
+* 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
 * })
+*
+* const lines: string[] = []
+* for await (const line of child.lines) lines.push(line)
+* lines // ['ready', 'done']
+*
+* const exit = await child.exit
+* exit.code // 0
+* await child.destroy()
 * ```
 */
 function createProcess(options) {
 	return new Process(options);
 }
 /**
-* Creates one raw byte session over a supervised child process.
+* Creates one raw byte session over a supervised child process and returns it as a
+* {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link SessionInterface}
@@ -2121,7 +2134,9 @@ function createSession(options) {
 	return new Session(options);
 }
 /**
-* Creates one keyed registry of supervised child processes.
+* Creates one empty keyed registry of supervised child processes and returns it as a
+* {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+* `ProcessManager` class.
 *
 * @param options - Initial fleet-level observation hooks and listener-error handling
 * @returns The {@link ProcessManagerInterface} registry