@gobing-ai/ts-runtime 0.4.57 → 0.4.58

package/README.md

@@ -598,17 +598,41 @@ unsub();
 ```
 
 `rejectOnError: true` throws on non-zero exits. `OutputPolicy` controls
-buffered vs streamed output. `ProcessOptions` supports timeout, env, cwd,
+buffered vs streamed output. `ProcessOptions` supports `timeout`, env, cwd,
 maxOutput, forceBuffered, an optional synchronous `onOutput({ stream, chunk,
 timestamp })` observer, and registry fields (`source`, `teamId`, `agentId`).
 `onOutput` observes live chunks while the returned `ProcessResult` retains the
 complete buffered stdout/stderr; observers must enqueue and return, and thrown
-observer errors are isolated from the child. When `signal` is supplied, one-shot
-commands run in an isolated process group on Unix so abort terminates descendants
-that could otherwise retain the output pipes; Windows falls back to direct-child
-cancellation. Inject the same `ProcessRegistry` into every executor that should
+observer errors are isolated from the child. Inject the same `ProcessRegistry` into every executor that should
 appear in one watch list; without a registry, behavior is unchanged.
 
+#### Deadlines, cancellation, and process-group containment (Unix)
+
+On Unix, a finite `timeout` or a supplied `signal` puts the run under executor-owned
+process-group containment: the child is spawned detached as a process-group leader, the
+executor runs one termination sequence (group `SIGTERM`, a `killGraceMs` grace — default
+5000 ms — then group `SIGKILL`), and escalation is driven by group liveness, never by the
+leader exiting first. Completion therefore reaps descendants that survive the leader while
+holding inherited output pipes or a SQLite write transaction, so `run()` completion is a
+containment barrier: after it resolves, no owned descendant remains (best-effort for
+SIGKILL-immune members — escalation gives up after a bounded settle). `runStreaming` keeps
+direct-child semantics and provides no group containment.
+
+- `timeout: number` — positive-integer deadline in ms; expiry reports `outcome: 'timeout'`.
+- `timeout: null` — unlimited; overrides a finite `defaultTimeout` from `ProcessExecutorConfig`.
+- omitted — inherits `defaultTimeout` (which may itself be `null`/unlimited).
+- `timeout: 0`, negative, fractional, `NaN`, `±Infinity`, or beyond the native timer range —
+  rejected with `TypeError` before spawn; `killGraceMs` must be a non-negative integer.
+- abort `signal` — reports `outcome: 'cancelled'`; a deadline is never a cancellation and
+  vice versa. Deadline and abort feed one escalation path, so callers must not arm a
+  competing watchdog over the same child.
+
+`ProcessResult.outcome` (`'exit' | 'timeout' | 'cancelled' | 'signal' | 'error'`, aliased as
+`ProcessExitReason`) states why the run ended; `process.exited` events carry the same reason.
+On Windows (and when no deadline or signal is supplied), execa's direct-child timeout and
+cancellation semantics apply unchanged: only the direct child is killed, and the outcome is
+classified from the result.
+
 Cloudflare Workers do not expose process execution; check
 `factory.capabilities.hasProcessExecution` first.
 

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { createNodeFileSystem, findProjectRoot } from './file-system-node';
 export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, readJsonFile, walkDir, writeJsonFile, } from './fs';
 export * from './path';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform';
-export type { OutputPolicy, PipeProcess, PipeProcessOptions, ProcessEventDetail, ProcessEventSink, ProcessEvents, ProcessExecutorConfig, ProcessExitReason, ProcessOptions, ProcessOutputChunk, ProcessResult, ProcessSignal, TracerPort, } from './process-executor';
+export type { OutputPolicy, PipeProcess, PipeProcessOptions, ProcessEventDetail, ProcessEventSink, ProcessEvents, ProcessExecutorConfig, ProcessExitReason, ProcessOptions, ProcessOutcome, ProcessOutputChunk, ProcessResult, ProcessSignal, TracerPort, } from './process-executor';
 export { NodeProcessExecutor, ProcessExecutor } from './process-executor';
 export type { InMemoryProcessRegistryOptions, ProcessExecution, ProcessExecutionBegin, ProcessExecutionComplete, ProcessExecutionFilter, ProcessExecutionSource, ProcessExecutionStatus, ProcessRegistry, ProcessRegistryEvent, } from './process-registry';
 export { createInMemoryProcessRegistry, InMemoryProcessRegistry } from './process-registry';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EACR,8BAA8B,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEnF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EACR,8BAA8B,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEnF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/process-executor.d.ts

@@ -24,7 +24,11 @@ export type OutputPolicy = {
 };
 /** Shared configuration for a process executor (default timeout, output buffering, output policy). */
 export interface ProcessExecutorConfig {
-    defaultTimeout?: number;
+    /**
+     * Default execution deadline inherited by runs that omit `timeout`. `null` makes the
+     * default policy unlimited; value validation follows `ProcessOptions.timeout`.
+     */
+    defaultTimeout?: number | null;
     defaultMaxOutput?: number;
     output?: OutputPolicy;
     events?: ProcessEventSink;
@@ -55,7 +59,23 @@ export interface ProcessOptions {
      * `run` and `runStreaming` share one contract.
      */
     envMode?: 'merge' | 'replace';
-    timeout?: number;
+    /**
+     * Execution deadline in milliseconds. Omitted inherits
+     * {@link ProcessExecutorConfig.defaultTimeout}; explicit `null` runs without a deadline
+     * (a supplied `signal` still cancels). On Unix, a finite deadline activates owned
+     * process-group containment: the executor arms its own timer — callers must not race a
+     * second watchdog — and expiry reaps the whole group with SIGTERM-to-SIGKILL escalation.
+     * Zero, negative, fractional, non-finite, or beyond-timer-range values are rejected
+     * before spawn; `null` replaces the previous `0`-disables behavior.
+     */
+    timeout?: number | null;
+    /**
+     * Grace in milliseconds between the owned group SIGTERM and the SIGKILL escalation
+     * (Unix group containment; see {@link ProcessOptions.timeout}). `0` escalates
+     * immediately; omitted defaults to 5000 ms. Out-of-range values are rejected before
+     * spawn. Without a finite deadline or `signal`, this option has no effect.
+     */
+    killGraceMs?: number;
     maxOutput?: number;
     label?: string;
     rejectOnError?: boolean;
@@ -98,6 +118,12 @@ export interface ProcessOutputChunk {
     readonly chunk: string;
     readonly timestamp: string;
 }
+/**
+ * Terminal classification of how a run ended: normal `exit`, deadline `timeout`, external
+ * `cancelled` abort, termination by an outside `signal`, or `error` (spawn/runtime failure).
+ * Reaping surviving owned descendants after a natural leader exit keeps the outcome `exit`.
+ */
+export type ProcessOutcome = 'exit' | 'timeout' | 'cancelled' | 'signal' | 'error';
 /** Result of a completed child process, including exit code, captured output, and duration. */
 export interface ProcessResult {
     command: string;
@@ -107,9 +133,15 @@ export interface ProcessResult {
     stderr: string;
     signal?: string;
     durationMs: number;
+    /**
+     * How the run terminated, distinguishing deadline expiry from external cancellation,
+     * an outside signal, runtime failure, and normal completion. Optional for backward
+     * compatibility with hand-built results; `NodeProcessExecutor` always sets it.
+     */
+    outcome?: ProcessOutcome;
 }
-/** Reason a process completion event was emitted. */
-export type ProcessExitReason = 'exit' | 'signal' | 'timeout' | 'error';
+/** Reason a process completion event was emitted (mirrors {@link ProcessOutcome}). */
+export type ProcessExitReason = ProcessOutcome;
 /** Payload emitted for process execution observability. */
 export interface ProcessEventDetail {
     command: string;

package/dist/process-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"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"}

package/dist/process-executor.js

@@ -4,7 +4,7 @@ import { getProcessEnv } from './config.js';
 function processEventSeverity(reason, exitCode) {
     if (reason === 'error')
         return 'error';
-    if (reason === 'timeout')
+    if (reason === 'timeout' || reason === 'cancelled')
         return 'warning';
     if (exitCode !== null && exitCode !== 0)
         return 'warning';
@@ -48,15 +48,25 @@ export class NodeProcessExecutor {
     }
     async runUntraced(options) {
         const args = options.args ?? [];
+        // Validate before spawn and before any registry/event side effects: an invalid
+        // deadline or grace is caller configuration error, not a process outcome.
+        const deadline = resolveDeadline(options.timeout, this.config.defaultTimeout);
+        const killGraceMs = resolveKillGraceMs(options.killGraceMs);
+        // Unix group containment activates on a finite deadline or a caller abort signal:
+        // the executor then owns group isolation, SIGTERM, escalation, output settlement
+        // and the final outcome, so callers must not arm a competing watchdog. Other
+        // platforms keep execa's direct-child timeout/cancellation semantics explicit.
+        const groupOwned = process.platform !== 'win32' && (typeof deadline === 'number' || options.signal !== undefined);
         const execaOptions = buildExecaOptions({
             cwd: options.cwd ?? this.config.paths?.cwd,
             env: options.env,
-            timeout: options.timeout ?? this.config.defaultTimeout,
+            timeout: typeof deadline === 'number' ? deadline : undefined,
             maxOutput: options.maxOutput ?? this.config.defaultMaxOutput,
             rejectOnError: options.rejectOnError ?? false,
             outputPolicy: this.config.output,
             forceBuffered: options.forceBuffered ?? false,
             signal: options.signal,
+            groupOwned,
         });
         const startedAt = Date.now();
         const startedIso = new Date(startedAt).toISOString();
@@ -77,8 +87,17 @@ export class NodeProcessExecutor {
             severity: 'info',
             ...(options.label !== undefined ? { label: options.label } : {}),
         });
+        let ownership;
         try {
             const subprocess = execa(options.command, args, execaOptions);
+            if (groupOwned && subprocess.pid !== undefined) {
+                ownership = ownProcessGroupLifecycle({
+                    pid: subprocess.pid,
+                    deadlineMs: typeof deadline === 'number' ? deadline : undefined,
+                    signal: options.signal,
+                    graceMs: killGraceMs,
+                });
+            }
             // execa@9's resolved Result carries no pid, but the live handle does.
             // Publish it while the child is running so observers can identify the
             // subprocess, and record it against the registry entry opened above.
@@ -93,10 +112,14 @@ export class NodeProcessExecutor {
                     }
                 }
             }
-            const stopGroupCancellation = observeProcessGroupCancellation(subprocess, options.signal);
+            const stopOwnedTermination = () => ownership?.stop();
             observeOutput(subprocess.stdout, 'stdout', options.onOutput);
             observeOutput(subprocess.stderr, 'stderr', options.onOutput);
-            const result = await subprocess.finally(stopGroupCancellation);
+            const result = await subprocess.finally(stopOwnedTermination);
+            // Settle the owned termination path before reporting: a deadline or abort that
+            // fired keeps escalating until the group is empty, and a natural leader exit
+            // reaps surviving owned descendants so completion cannot leak pipes or locks.
+            const ownedOutcome = ownership !== undefined ? await ownership.finish() : undefined;
             const processResult = {
                 command: options.command,
                 args,
@@ -105,6 +128,7 @@ export class NodeProcessExecutor {
                 stderr: asString(result.stderr),
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
+                outcome: ownedOutcome ?? (result.signalDescription !== undefined ? 'signal' : 'exit'),
             };
             this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, result);
@@ -112,6 +136,9 @@ export class NodeProcessExecutor {
         }
         catch (error) {
             const failed = error;
+            // Termination containment settles before the failure is reported — and before
+            // rejectOnError rethrows — so a rejected run never leaks owned descendants.
+            const ownedOutcome = ownership !== undefined ? await ownership.finish() : undefined;
             const processResult = {
                 command: options.command,
                 args,
@@ -124,6 +151,7 @@ export class NodeProcessExecutor {
                         ? { signal: failed.signal }
                         : {}),
                 durationMs: failed.durationMs ?? Date.now() - startedAt,
+                outcome: ownedOutcome ?? classifyFailedCompletion(failed),
             };
             this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, error, error);
@@ -227,13 +255,8 @@ export class NodeProcessExecutor {
         });
     }
     emitExitedFromResult(options, result, completion, error) {
-        const reason = isTimedOut(completion)
-            ? 'timeout'
-            : result.signal !== undefined
-                ? 'signal'
-                : error
-                    ? 'error'
-                    : 'exit';
+        const reason = result.outcome ??
+            (isTimedOut(completion) ? 'timeout' : result.signal !== undefined ? 'signal' : error ? 'error' : 'exit');
         this.emitProcessEvent('process.exited', {
             command: result.command,
             args: result.args,
@@ -401,37 +424,158 @@ function buildExecaOptions(opts) {
                 : { all: true }),
         ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
         ...(opts.env !== undefined ? { env: opts.env } : {}),
-        ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+        ...(opts.timeout !== undefined && !opts.groupOwned ? { timeout: opts.timeout } : {}),
         ...(opts.maxOutput !== undefined ? { maxBuffer: opts.maxOutput } : {}),
-        ...(opts.signal !== undefined
-            ? {
-                cancelSignal: opts.signal,
-                // Node's negative-pid group signal requires the child to lead
-                // a distinct process group. Windows has no equivalent.
-                ...(process.platform !== 'win32' ? { detached: true } : {}),
-            }
-            : {}),
+        // Group-owned runs make the child lead a distinct process group so negative-pid
+        // signaling can reach the whole tree; termination itself runs through the
+        // executor's own escalation path (deadline and abort feed one sequence).
+        // Platforms without Unix group semantics cancel the direct child via execa.
+        ...(opts.groupOwned ? { detached: true } : {}),
+        ...(opts.signal !== undefined && !opts.groupOwned ? { cancelSignal: opts.signal } : {}),
     };
 }
-function observeProcessGroupCancellation(subprocess, signal) {
-    const pid = subprocess.pid;
-    if (signal === undefined || process.platform === 'win32' || pid === undefined)
-        return () => { };
-    const abort = () => {
-        try {
-            process.kill(-pid, 'SIGTERM');
-        }
-        catch {
-            // The leader may already have exited through execa's cancelSignal.
-            // Fall back to the direct child without changing cancellation semantics.
-            subprocess.kill('SIGTERM');
-        }
+// ── Deadline and process-group containment ───────────────────────────
+/**
+ * Largest delay accepted by native timers; anything larger would overflow onto an
+ * immediate timer, so deadline/grace values beyond it are rejected before spawn.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Default grace between the owned group SIGTERM and the SIGKILL escalation. */
+const DEFAULT_KILL_GRACE_MS = 5000;
+/** Poll cadence while waiting for an owned process group to empty. */
+const GROUP_POLL_INTERVAL_MS = 25;
+/** Bounded patience after group SIGKILL before giving up on unkillable (D-state) members. */
+const GROUP_KILL_PATIENCE_MS = 2000;
+/**
+ * Resolve the effective deadline: omitted inherits the executor default (which may itself
+ * be unlimited), explicit `null` is unlimited and overrides any finite default, and a
+ * finite value must be a positive integer within the native timer range. Invalid values
+ * are rejected before spawn — never clamped and never overflowed onto a timer.
+ */
+function resolveDeadline(optionTimeout, defaultTimeout) {
+    if (optionTimeout === null)
+        return null;
+    const candidate = optionTimeout === undefined ? defaultTimeout : optionTimeout;
+    if (candidate === undefined || candidate === null)
+        return candidate;
+    if (!Number.isInteger(candidate) || candidate <= 0 || candidate > MAX_TIMEOUT_MS) {
+        throw new TypeError(`Process timeout must be a positive integer within the native timer range (1-${MAX_TIMEOUT_MS} ms), got ${String(candidate)}`);
+    }
+    return candidate;
+}
+/**
+ * Resolve the SIGTERM→SIGKILL escalation grace: omitted uses {@link DEFAULT_KILL_GRACE_MS},
+ * `0` escalates immediately, and anything outside the native timer range is rejected.
+ */
+function resolveKillGraceMs(optionGraceMs) {
+    if (optionGraceMs === undefined)
+        return DEFAULT_KILL_GRACE_MS;
+    if (!Number.isInteger(optionGraceMs) || optionGraceMs < 0 || optionGraceMs > MAX_TIMEOUT_MS) {
+        throw new TypeError(`Process killGraceMs must be a non-negative integer within the native timer range (0-${MAX_TIMEOUT_MS} ms), got ${String(optionGraceMs)}`);
+    }
+    return optionGraceMs;
+}
+/** Whether any member of the owned process group is still alive (signal 0 probe on `-pid`). */
+function groupExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the group exists but is not signallable from here.
+        return error.code === 'EPERM';
+    }
+}
+/** Signal the owned process group; `false` when the group is already gone (ESRCH). */
+function signalGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForGroupExit(pid, budgetMs) {
+    const giveUpAt = Date.now() + budgetMs;
+    while (groupExists(pid)) {
+        if (Date.now() >= giveUpAt)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, GROUP_POLL_INTERVAL_MS));
+    }
+    return true;
+}
+/**
+ * The one termination sequence for an owned Unix process group: group SIGTERM, wait the
+ * grace for the whole group to empty, then group SIGKILL and a bounded settle wait.
+ * Group liveness — not direct-child exit — decides completion, so escalation is never
+ * cancelled because the leader exited first while descendants retain pipes or locks.
+ * Resolves `true` only when a group signal was actually delivered.
+ */
+async function reapProcessGroup(pid, graceMs) {
+    if (!signalGroup(pid, 'SIGTERM'))
+        return false;
+    if (await waitForGroupExit(pid, graceMs))
+        return true;
+    signalGroup(pid, 'SIGKILL');
+    await waitForGroupExit(pid, GROUP_KILL_PATIENCE_MS);
+    return true;
+}
+/**
+ * Own one detached child's process group on Unix. A deadline timer and the caller's abort
+ * signal both feed a single termination path — group SIGTERM, grace, SIGKILL — and after a
+ * natural leader exit surviving owned descendants are reaped with the same sequence, so
+ * completion cannot leak group members holding inherited pipes or database write locks.
+ */
+function ownProcessGroupLifecycle(ownership) {
+    const { pid, graceMs } = ownership;
+    let trigger;
+    let termination;
+    let timer;
+    const initiate = (reason) => {
+        if (trigger !== undefined)
+            return;
+        trigger = reason;
+        termination = reapProcessGroup(pid, graceMs);
     };
-    if (signal.aborted)
-        abort();
-    else
-        signal.addEventListener('abort', abort, { once: true });
-    return () => signal.removeEventListener('abort', abort);
+    if (ownership.deadlineMs !== undefined) {
+        timer = setTimeout(() => initiate('timeout'), ownership.deadlineMs);
+    }
+    const onAbort = () => initiate('cancelled');
+    if (ownership.signal !== undefined) {
+        if (ownership.signal.aborted)
+            onAbort();
+        else
+            ownership.signal.addEventListener('abort', onAbort, { once: true });
+    }
+    return {
+        finish: async () => {
+            if (trigger === undefined) {
+                // Natural completion: reap stragglers (no-op when the group is already empty).
+                await reapProcessGroup(pid, graceMs);
+                return undefined;
+            }
+            // An undeliverable trigger (group already gone — the child finished first)
+            // yields undefined so the outcome falls back to the natural classification.
+            return (await termination) ? trigger : undefined;
+        },
+        stop: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            ownership.signal?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/** Classify an execa rejection on paths where the executor did not own the termination. */
+function classifyFailedCompletion(error) {
+    if (error.timedOut === true)
+        return 'timeout';
+    if (error.isCanceled === true)
+        return 'cancelled';
+    if (error.isTerminated === true || error.signalDescription !== undefined || error.signal !== undefined) {
+        return 'signal';
+    }
+    return 'error';
 }
 function observeOutput(stream, name, observer) {
     if (!stream || !observer)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.57",
+    "version": "0.4.58",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,17 +58,17 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-runtime-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.57",
+        "@gobing-ai/ts-utils": "^0.4.58",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.57",
+        "@gobing-ai/ts-db": "^0.4.58",
         "@types/bun": "1.3.14"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.57"
+        "@gobing-ai/ts-db": "^0.4.58"
     },
     "peerDependenciesMeta": {
         "@gobing-ai/ts-db": {

package/src/index.ts

@@ -26,6 +26,7 @@ export type {
     ProcessExecutorConfig,
     ProcessExitReason,
     ProcessOptions,
+    ProcessOutcome,
     ProcessOutputChunk,
     ProcessResult,
     ProcessSignal,

package/src/process-executor.ts

@@ -24,7 +24,11 @@ export type OutputPolicy = { mode: 'buffered' } | { mode: 'stream'; isTTY?: bool
 
 /** Shared configuration for a process executor (default timeout, output buffering, output policy). */
 export interface ProcessExecutorConfig {
-    defaultTimeout?: number;
+    /**
+     * Default execution deadline inherited by runs that omit `timeout`. `null` makes the
+     * default policy unlimited; value validation follows `ProcessOptions.timeout`.
+     */
+    defaultTimeout?: number | null;
     defaultMaxOutput?: number;
     output?: OutputPolicy;
     events?: ProcessEventSink;
@@ -56,7 +60,23 @@ export interface ProcessOptions {
      * `run` and `runStreaming` share one contract.
      */
     envMode?: 'merge' | 'replace';
-    timeout?: number;
+    /**
+     * Execution deadline in milliseconds. Omitted inherits
+     * {@link ProcessExecutorConfig.defaultTimeout}; explicit `null` runs without a deadline
+     * (a supplied `signal` still cancels). On Unix, a finite deadline activates owned
+     * process-group containment: the executor arms its own timer — callers must not race a
+     * second watchdog — and expiry reaps the whole group with SIGTERM-to-SIGKILL escalation.
+     * Zero, negative, fractional, non-finite, or beyond-timer-range values are rejected
+     * before spawn; `null` replaces the previous `0`-disables behavior.
+     */
+    timeout?: number | null;
+    /**
+     * Grace in milliseconds between the owned group SIGTERM and the SIGKILL escalation
+     * (Unix group containment; see {@link ProcessOptions.timeout}). `0` escalates
+     * immediately; omitted defaults to 5000 ms. Out-of-range values are rejected before
+     * spawn. Without a finite deadline or `signal`, this option has no effect.
+     */
+    killGraceMs?: number;
     maxOutput?: number;
     label?: string;
     rejectOnError?: boolean;
@@ -101,6 +121,13 @@ export interface ProcessOutputChunk {
     readonly timestamp: string;
 }
 
+/**
+ * Terminal classification of how a run ended: normal `exit`, deadline `timeout`, external
+ * `cancelled` abort, termination by an outside `signal`, or `error` (spawn/runtime failure).
+ * Reaping surviving owned descendants after a natural leader exit keeps the outcome `exit`.
+ */
+export type ProcessOutcome = 'exit' | 'timeout' | 'cancelled' | 'signal' | 'error';
+
 /** Result of a completed child process, including exit code, captured output, and duration. */
 export interface ProcessResult {
     command: string;
@@ -110,14 +137,20 @@ export interface ProcessResult {
     stderr: string;
     signal?: string;
     durationMs: number;
+    /**
+     * How the run terminated, distinguishing deadline expiry from external cancellation,
+     * an outside signal, runtime failure, and normal completion. Optional for backward
+     * compatibility with hand-built results; `NodeProcessExecutor` always sets it.
+     */
+    outcome?: ProcessOutcome;
 }
 
-/** Reason a process completion event was emitted. */
-export type ProcessExitReason = 'exit' | 'signal' | 'timeout' | 'error';
+/** Reason a process completion event was emitted (mirrors {@link ProcessOutcome}). */
+export type ProcessExitReason = ProcessOutcome;
 
 function processEventSeverity(reason: ProcessExitReason, exitCode: number | null): ProcessEventDetail['severity'] {
     if (reason === 'error') return 'error';
-    if (reason === 'timeout') return 'warning';
+    if (reason === 'timeout' || reason === 'cancelled') return 'warning';
     if (exitCode !== null && exitCode !== 0) return 'warning';
     return 'info';
 }
@@ -263,15 +296,26 @@ export class NodeProcessExecutor implements ProcessExecutor {
 
     private async runUntraced(options: ProcessOptions): Promise<ProcessResult> {
         const args = options.args ?? [];
+        // Validate before spawn and before any registry/event side effects: an invalid
+        // deadline or grace is caller configuration error, not a process outcome.
+        const deadline = resolveDeadline(options.timeout, this.config.defaultTimeout);
+        const killGraceMs = resolveKillGraceMs(options.killGraceMs);
+        // Unix group containment activates on a finite deadline or a caller abort signal:
+        // the executor then owns group isolation, SIGTERM, escalation, output settlement
+        // and the final outcome, so callers must not arm a competing watchdog. Other
+        // platforms keep execa's direct-child timeout/cancellation semantics explicit.
+        const groupOwned =
+            process.platform !== 'win32' && (typeof deadline === 'number' || options.signal !== undefined);
         const execaOptions = buildExecaOptions({
             cwd: options.cwd ?? this.config.paths?.cwd,
             env: options.env,
-            timeout: options.timeout ?? this.config.defaultTimeout,
+            timeout: typeof deadline === 'number' ? deadline : undefined,
             maxOutput: options.maxOutput ?? this.config.defaultMaxOutput,
             rejectOnError: options.rejectOnError ?? false,
             outputPolicy: this.config.output,
             forceBuffered: options.forceBuffered ?? false,
             signal: options.signal,
+            groupOwned,
         });
         const startedAt = Date.now();
         const startedIso = new Date(startedAt).toISOString();
@@ -293,8 +337,17 @@ export class NodeProcessExecutor implements ProcessExecutor {
             ...(options.label !== undefined ? { label: options.label } : {}),
         });
 
+        let ownership: ProcessGroupOwnership | undefined;
         try {
             const subprocess = execa(options.command, args, execaOptions);
+            if (groupOwned && subprocess.pid !== undefined) {
+                ownership = ownProcessGroupLifecycle({
+                    pid: subprocess.pid,
+                    deadlineMs: typeof deadline === 'number' ? deadline : undefined,
+                    signal: options.signal,
+                    graceMs: killGraceMs,
+                });
+            }
             // execa@9's resolved Result carries no pid, but the live handle does.
             // Publish it while the child is running so observers can identify the
             // subprocess, and record it against the registry entry opened above.
@@ -308,10 +361,14 @@ export class NodeProcessExecutor implements ProcessExecutor {
                     }
                 }
             }
-            const stopGroupCancellation = observeProcessGroupCancellation(subprocess, options.signal);
+            const stopOwnedTermination = (): void => ownership?.stop();
             observeOutput(subprocess.stdout, 'stdout', options.onOutput);
             observeOutput(subprocess.stderr, 'stderr', options.onOutput);
-            const result = await subprocess.finally(stopGroupCancellation);
+            const result = await subprocess.finally(stopOwnedTermination);
+            // Settle the owned termination path before reporting: a deadline or abort that
+            // fired keeps escalating until the group is empty, and a natural leader exit
+            // reaps surviving owned descendants so completion cannot leak pipes or locks.
+            const ownedOutcome = ownership !== undefined ? await ownership.finish() : undefined;
             const processResult = {
                 command: options.command,
                 args,
@@ -320,6 +377,8 @@ export class NodeProcessExecutor implements ProcessExecutor {
                 stderr: asString(result.stderr),
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
+                outcome:
+                    ownedOutcome ?? (result.signalDescription !== undefined ? ('signal' as const) : ('exit' as const)),
             };
             this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, result);
@@ -333,8 +392,13 @@ export class NodeProcessExecutor implements ProcessExecutor {
                 signal?: string;
                 durationMs?: number;
                 timedOut?: boolean;
+                isCanceled?: boolean;
+                isTerminated?: boolean;
                 message?: string;
             };
+            // Termination containment settles before the failure is reported — and before
+            // rejectOnError rethrows — so a rejected run never leaks owned descendants.
+            const ownedOutcome = ownership !== undefined ? await ownership.finish() : undefined;
             const processResult = {
                 command: options.command,
                 args,
@@ -347,6 +411,7 @@ export class NodeProcessExecutor implements ProcessExecutor {
                       ? { signal: failed.signal }
                       : {}),
                 durationMs: failed.durationMs ?? Date.now() - startedAt,
+                outcome: ownedOutcome ?? classifyFailedCompletion(failed),
             };
             this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, error, error);
@@ -465,13 +530,9 @@ export class NodeProcessExecutor implements ProcessExecutor {
         completion: unknown,
         error?: unknown,
     ): void {
-        const reason = isTimedOut(completion)
-            ? 'timeout'
-            : result.signal !== undefined
-              ? 'signal'
-              : error
-                ? 'error'
-                : 'exit';
+        const reason =
+            result.outcome ??
+            (isTimedOut(completion) ? 'timeout' : result.signal !== undefined ? 'signal' : error ? 'error' : 'exit');
         this.emitProcessEvent('process.exited', {
             command: result.command,
             args: result.args,
@@ -678,6 +739,7 @@ function buildExecaOptions(opts: {
     outputPolicy: OutputPolicy | undefined;
     forceBuffered: boolean;
     signal?: AbortSignal;
+    groupOwned: boolean;
 }): ExecaOptions {
     const mode = opts.forceBuffered ? 'buffered' : (opts.outputPolicy?.mode ?? 'buffered');
     const streamToTerminal =
@@ -695,37 +757,191 @@ function buildExecaOptions(opts: {
               : { all: true }),
         ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
         ...(opts.env !== undefined ? { env: opts.env } : {}),
-        ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+        ...(opts.timeout !== undefined && !opts.groupOwned ? { timeout: opts.timeout } : {}),
         ...(opts.maxOutput !== undefined ? { maxBuffer: opts.maxOutput } : {}),
-        ...(opts.signal !== undefined
-            ? {
-                  cancelSignal: opts.signal,
-                  // Node's negative-pid group signal requires the child to lead
-                  // a distinct process group. Windows has no equivalent.
-                  ...(process.platform !== 'win32' ? { detached: true } : {}),
-              }
-            : {}),
+        // Group-owned runs make the child lead a distinct process group so negative-pid
+        // signaling can reach the whole tree; termination itself runs through the
+        // executor's own escalation path (deadline and abort feed one sequence).
+        // Platforms without Unix group semantics cancel the direct child via execa.
+        ...(opts.groupOwned ? { detached: true } : {}),
+        ...(opts.signal !== undefined && !opts.groupOwned ? { cancelSignal: opts.signal } : {}),
     };
 }
 
-function observeProcessGroupCancellation(
-    subprocess: { pid?: number; kill(signal?: NodeJS.Signals | number): boolean },
-    signal: AbortSignal | undefined,
-): () => void {
-    const pid = subprocess.pid;
-    if (signal === undefined || process.platform === 'win32' || pid === undefined) return () => {};
-    const abort = (): void => {
-        try {
-            process.kill(-pid, 'SIGTERM');
-        } catch {
-            // The leader may already have exited through execa's cancelSignal.
-            // Fall back to the direct child without changing cancellation semantics.
-            subprocess.kill('SIGTERM');
-        }
+// ── Deadline and process-group containment ───────────────────────────
+
+/**
+ * Largest delay accepted by native timers; anything larger would overflow onto an
+ * immediate timer, so deadline/grace values beyond it are rejected before spawn.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/** Default grace between the owned group SIGTERM and the SIGKILL escalation. */
+const DEFAULT_KILL_GRACE_MS = 5000;
+
+/** Poll cadence while waiting for an owned process group to empty. */
+const GROUP_POLL_INTERVAL_MS = 25;
+
+/** Bounded patience after group SIGKILL before giving up on unkillable (D-state) members. */
+const GROUP_KILL_PATIENCE_MS = 2000;
+
+/**
+ * Resolve the effective deadline: omitted inherits the executor default (which may itself
+ * be unlimited), explicit `null` is unlimited and overrides any finite default, and a
+ * finite value must be a positive integer within the native timer range. Invalid values
+ * are rejected before spawn — never clamped and never overflowed onto a timer.
+ */
+function resolveDeadline(
+    optionTimeout: number | null | undefined,
+    defaultTimeout: number | null | undefined,
+): number | null | undefined {
+    if (optionTimeout === null) return null;
+    const candidate = optionTimeout === undefined ? defaultTimeout : optionTimeout;
+    if (candidate === undefined || candidate === null) return candidate;
+    if (!Number.isInteger(candidate) || candidate <= 0 || candidate > MAX_TIMEOUT_MS) {
+        throw new TypeError(
+            `Process timeout must be a positive integer within the native timer range (1-${MAX_TIMEOUT_MS} ms), got ${String(candidate)}`,
+        );
+    }
+    return candidate;
+}
+
+/**
+ * Resolve the SIGTERM→SIGKILL escalation grace: omitted uses {@link DEFAULT_KILL_GRACE_MS},
+ * `0` escalates immediately, and anything outside the native timer range is rejected.
+ */
+function resolveKillGraceMs(optionGraceMs: number | undefined): number {
+    if (optionGraceMs === undefined) return DEFAULT_KILL_GRACE_MS;
+    if (!Number.isInteger(optionGraceMs) || optionGraceMs < 0 || optionGraceMs > MAX_TIMEOUT_MS) {
+        throw new TypeError(
+            `Process killGraceMs must be a non-negative integer within the native timer range (0-${MAX_TIMEOUT_MS} ms), got ${String(optionGraceMs)}`,
+        );
+    }
+    return optionGraceMs;
+}
+
+/** Whether any member of the owned process group is still alive (signal 0 probe on `-pid`). */
+function groupExists(pid: number): boolean {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    } catch (error) {
+        // EPERM means the group exists but is not signallable from here.
+        return (error as NodeJS.ErrnoException).code === 'EPERM';
+    }
+}
+
+/** Signal the owned process group; `false` when the group is already gone (ESRCH). */
+function signalGroup(pid: number, signal: NodeJS.Signals | number): boolean {
+    try {
+        process.kill(-pid, signal);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function waitForGroupExit(pid: number, budgetMs: number): Promise<boolean> {
+    const giveUpAt = Date.now() + budgetMs;
+    while (groupExists(pid)) {
+        if (Date.now() >= giveUpAt) return false;
+        await new Promise<void>((resolve) => setTimeout(resolve, GROUP_POLL_INTERVAL_MS));
+    }
+    return true;
+}
+
+/**
+ * The one termination sequence for an owned Unix process group: group SIGTERM, wait the
+ * grace for the whole group to empty, then group SIGKILL and a bounded settle wait.
+ * Group liveness — not direct-child exit — decides completion, so escalation is never
+ * cancelled because the leader exited first while descendants retain pipes or locks.
+ * Resolves `true` only when a group signal was actually delivered.
+ */
+async function reapProcessGroup(pid: number, graceMs: number): Promise<boolean> {
+    if (!signalGroup(pid, 'SIGTERM')) return false;
+    if (await waitForGroupExit(pid, graceMs)) return true;
+    signalGroup(pid, 'SIGKILL');
+    await waitForGroupExit(pid, GROUP_KILL_PATIENCE_MS);
+    return true;
+}
+
+/** Handle for the executor-owned termination of one spawned process group. */
+interface ProcessGroupOwnership {
+    /**
+     * Settle the run's termination: resolve the outcome delivered by the executor's own
+     * path (deadline `timeout` or external `cancelled`) after the escalation completed, or
+     * reap surviving owned descendants after a natural leader exit (outcome stays `exit`).
+     * Call exactly once, after the execa promise has settled; bounded, never hangs.
+     */
+    finish(): Promise<ProcessOutcome | undefined>;
+    /** Release the deadline timer and abort listener once the execa promise has settled. */
+    stop(): void;
+}
+
+/**
+ * Own one detached child's process group on Unix. A deadline timer and the caller's abort
+ * signal both feed a single termination path — group SIGTERM, grace, SIGKILL — and after a
+ * natural leader exit surviving owned descendants are reaped with the same sequence, so
+ * completion cannot leak group members holding inherited pipes or database write locks.
+ */
+function ownProcessGroupLifecycle(ownership: {
+    pid: number;
+    deadlineMs: number | undefined;
+    signal: AbortSignal | undefined;
+    graceMs: number;
+}): ProcessGroupOwnership {
+    const { pid, graceMs } = ownership;
+    let trigger: 'timeout' | 'cancelled' | undefined;
+    let termination: Promise<boolean> | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const initiate = (reason: 'timeout' | 'cancelled'): void => {
+        if (trigger !== undefined) return;
+        trigger = reason;
+        termination = reapProcessGroup(pid, graceMs);
+    };
+
+    if (ownership.deadlineMs !== undefined) {
+        timer = setTimeout(() => initiate('timeout'), ownership.deadlineMs);
+    }
+    const onAbort = (): void => initiate('cancelled');
+    if (ownership.signal !== undefined) {
+        if (ownership.signal.aborted) onAbort();
+        else ownership.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    return {
+        finish: async () => {
+            if (trigger === undefined) {
+                // Natural completion: reap stragglers (no-op when the group is already empty).
+                await reapProcessGroup(pid, graceMs);
+                return undefined;
+            }
+            // An undeliverable trigger (group already gone — the child finished first)
+            // yields undefined so the outcome falls back to the natural classification.
+            return (await termination) ? trigger : undefined;
+        },
+        stop: () => {
+            if (timer !== undefined) clearTimeout(timer);
+            ownership.signal?.removeEventListener('abort', onAbort);
+        },
     };
-    if (signal.aborted) abort();
-    else signal.addEventListener('abort', abort, { once: true });
-    return () => signal.removeEventListener('abort', abort);
+}
+
+/** Classify an execa rejection on paths where the executor did not own the termination. */
+function classifyFailedCompletion(error: {
+    timedOut?: boolean;
+    isCanceled?: boolean;
+    isTerminated?: boolean;
+    signalDescription?: string;
+    signal?: string;
+}): ProcessOutcome {
+    if (error.timedOut === true) return 'timeout';
+    if (error.isCanceled === true) return 'cancelled';
+    if (error.isTerminated === true || error.signalDescription !== undefined || error.signal !== undefined) {
+        return 'signal';
+    }
+    return 'error';
 }
 
 function observeOutput(