stitchkit 0.105.1 → 0.105.2

package/CHANGELOG.md

@@ -15,6 +15,21 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.105.2] - 2026-10-06
+
+### Added
+
+- `stitchkit/process` — `runNativeCommand` takes `onLeaderStarted({ pid })`, called once right
+  after the leader exists (a throw stops the command with that error), and `drainTimeoutMs`,
+  which bounds how long the output pipes may stay open after the leader exited: a holder that
+  left the group with `setsid` otherwise keeps the command waiting until `timeoutMs` or the
+  signal, and with the bound it ends with `COMMAND_CLEANUP`.
+
+### Documentation
+
+- `stitchkit/process` — the native IO guide no longer says that `cleanupTimeoutMs` bounds the drain
+  after the leader exited; it bounds the wait after a stop, and `drainTimeoutMs` bounds the drain.
+
 ## [0.105.1] - 2026-10-06
 
 ### Added

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -7,10 +7,10 @@ import {
   AgentCodingToolAuthorizationSchema2,
   AgentCodingToolPathAuthorizationSchema2,
   createAgentCodingTools2
-} from "../../index-y7k2cdgv.js";
+} from "../../index-sevbwsnn.js";
 import"../../index-v5ee8ath.js";
 import"../../index-j4zh647a.js";
-import"../../index-5c26631f.js";
+import"../../index-3s86a7kf.js";
 import"../../index-8ks9b85e.js";
 import"../../index-gxm9rc97.js";
 import"../../index-yvfk3y36.js";

package/dist/entrypoints/agent-runtime/sandbox.js

@@ -9,7 +9,7 @@ import"../../index-r393tnfp.js";
 import"../../index-rpzewktb.js";
 import {
   createAgentCodingTools2
-} from "../../index-y7k2cdgv.js";
+} from "../../index-sevbwsnn.js";
 import"../../index-v5ee8ath.js";
 import"../../index-j4zh647a.js";
 import {
@@ -19,7 +19,7 @@ import {
   nativeCommandOwner,
   terminateOwnedGroup,
   startNativeCommand
-} from "../../index-5c26631f.js";
+} from "../../index-3s86a7kf.js";
 import"../../index-gxm9rc97.js";
 import {
   MAX_TIMER_MS

package/dist/entrypoints/process.js

@@ -7,7 +7,7 @@ import {
 import {
   NativeCommandError2,
   startNativeCommand
-} from "../index-5c26631f.js";
+} from "../index-3s86a7kf.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;

package/dist/{index-5c26631f.js → index-3s86a7kf.js}

@@ -51,6 +51,8 @@ var NativeCommandOptionsSchema = z.strictObject({
   maxStdinBytes: z.number().int().positive().default(1024 * 1024),
   onOutput: z.custom((v) => typeof v === "function").optional(),
   onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
+  onLeaderStarted: z.custom((v) => typeof v === "function").optional(),
+  drainTimeoutMs: z.number().int().positive().max(MAX_TIMER_MS).optional(),
   stop: NativeCommandStopPolicySchema.default({
     target: "group",
     signal: "SIGTERM",
@@ -748,7 +750,7 @@ function startNativeCommand(input, onSpawn, driver) {
   const stderr = [];
   let total = 0;
   const { stdout: output, stderr: errorOutput, leader, closed } = launched;
-  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs, controller);
+  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs ?? options.drainTimeoutMs, controller);
   const drain = async (stream, channel, captured) => {
     for await (const chunk of stream) {
       if (controller.signal.aborted)
@@ -790,6 +792,9 @@ function startNativeCommand(input, onSpawn, driver) {
   const run = (async () => {
     try {
       launched.start();
+      const pid = acquired?.child.pid;
+      if (pid !== undefined)
+        options.onLeaderStarted?.({ pid });
       const drains = Promise.all([
         drain(output, "stdout", stdout),
         drain(errorOutput, "stderr", stderr)

package/dist/{index-y7k2cdgv.js → index-sevbwsnn.js}

@@ -12,7 +12,7 @@ import {
   NativeCommandError2,
   CommandStopped,
   startNativeCommand
-} from "./index-5c26631f.js";
+} from "./index-3s86a7kf.js";
 import {
   probeAgentProcessSandboxOutcome,
   missingSandboxRestrictions2,

package/dist/process/command-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-owner.d.ts","sourceRoot":"","sources":["../../src/process/command-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAIzE,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAMlB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,yBAAyB;;;;;;;;;;EA+LnC"}
+{"version":3,"file":"command-owner.d.ts","sourceRoot":"","sources":["../../src/process/command-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAIzE,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAMlB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,yBAAyB;;;;;;;;;;EAiMnC"}

package/dist/process/contract.d.ts

@@ -58,6 +58,12 @@ export declare const NativeCommandOptionsSchema: z.ZodObject<{
     maxStdinBytes: z.ZodDefault<z.ZodNumber>;
     onOutput: z.ZodOptional<z.ZodCustom<(bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>, (bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>>>;
     onLeaderSettled: z.ZodOptional<z.ZodCustom<(event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>, (event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>>>;
+    onLeaderStarted: z.ZodOptional<z.ZodCustom<(event: {
+        pid: number;
+    }) => void, (event: {
+        pid: number;
+    }) => void>>;
+    drainTimeoutMs: z.ZodOptional<z.ZodNumber>;
     stop: z.ZodDefault<z.ZodObject<{
         target: z.ZodEnum<{
             group: "group";

package/dist/process/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,6BAA6B;;;;;;;2BAOjC,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,QAAA,MAAM,6BAA6B;;;;;;;;;;;;;;;kBAOjC,CAAC;AACH;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAqB3F,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAqBpB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAKX,uBAAuB,UAAU,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;kBA+CzF,CAAC;AACL;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACrF,QAAA,MAAM,yBAAyB;;;;;;iBAU7B,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,8BAA8B;;;EAAwC,CAAC;AAE7E;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAezB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IAdnF,2GAA2G;IAC3G,SAAgB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,GAAG,SAAS,CAAC;IAEnF,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;KAAE,EACpF;IACF,YACE,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,KAAK,CAAA;KAAE,EAC3C;CAgBH"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,6BAA6B;;;;;;;2BAOjC,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,QAAA,MAAM,6BAA6B;;;;;;;;;;;;;;;kBAOjC,CAAC;AACH;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAqB3F,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAqBpB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAKX,uBAAuB,UAAU,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAMrE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;kBAgD5C,CAAC;AACL;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACrF,QAAA,MAAM,yBAAyB;;;;;;iBAU7B,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,8BAA8B;;;EAAwC,CAAC;AAE7E;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAezB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IAdnF,2GAA2G;IAC3G,SAAgB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,GAAG,SAAS,CAAC;IAEnF,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;KAAE,EACpF;IACF,YACE,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,KAAK,CAAA;KAAE,EAC3C;CAgBH"}

package/llms/process.txt

@@ -298,14 +298,18 @@ decoder and the operator sink stay with the application. Long signal-only comman
 bounded tar or capture commands get their own explicit limits.
 
 A child the caller holds until it exits is the same call. A guardian that forwards its own SIGTERM
-passes an abort signal and `stop: { target: 'leader', signal: 'SIGTERM', graceMs }`; it reads the
-exit code in `onLeaderSettled`, before the pipes drain, and stderr through `onOutput` or `capture`
-with `maxOutputBytes`, and `cleanupTimeoutMs` bounds the drain (`COMMAND_CLEANUP` when a holder
-keeps the pipe past it). A worker whose whole group must stop on abort is the default
-`target: 'group'`. A child that inherits the caller's terminal is outside this capability: every
-command runs in a group of its own, and a background group that reads the terminal is stopped
-by the kernel (`SIGTTIN`), so an interactive re-execution stays a plain spawn in the caller's
-group. Importing one leaf does not make
+passes an abort signal and `stop: { target: 'leader', signal: 'SIGTERM', graceMs }`. It records the
+pid in `onLeaderStarted({ pid })`, which runs once right after the leader exists (a throw stops the
+command with that error), reads the exit code and signal in `onLeaderSettled` before the pipes
+drain, and reads stderr through `onOutput` or `capture` with `maxOutputBytes`. `drainTimeoutMs`
+bounds how long the output pipes may stay open after the leader exited: a holder that left the
+group with `setsid` keeps them open, and without the option the command waits for it until
+`timeoutMs` or the signal; with it the command ends with `COMMAND_CLEANUP` (a holder inside the
+group is already stopped by `descendants`). A worker whose whole group must stop on abort is the
+default `target: 'group'`. A child that inherits the caller's terminal is outside this
+capability: every command runs in a group of its own, and a background group that reads the
+terminal is stopped by the kernel (`SIGTTIN`), so an interactive re-execution stays a plain
+spawn in the caller's group. Importing one leaf does not make
 installing the whole npm package smaller; choose a dependency after measuring packed size and its
 dependency closure.
 
@@ -570,7 +574,7 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `onLeaderStarted({ pid })` (once, after the leader exists), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
 | `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |

package/llms-full.txt

@@ -8440,14 +8440,18 @@ decoder and the operator sink stay with the application. Long signal-only comman
 bounded tar or capture commands get their own explicit limits.
 
 A child the caller holds until it exits is the same call. A guardian that forwards its own SIGTERM
-passes an abort signal and `stop: { target: 'leader', signal: 'SIGTERM', graceMs }`; it reads the
-exit code in `onLeaderSettled`, before the pipes drain, and stderr through `onOutput` or `capture`
-with `maxOutputBytes`, and `cleanupTimeoutMs` bounds the drain (`COMMAND_CLEANUP` when a holder
-keeps the pipe past it). A worker whose whole group must stop on abort is the default
-`target: 'group'`. A child that inherits the caller's terminal is outside this capability: every
-command runs in a group of its own, and a background group that reads the terminal is stopped
-by the kernel (`SIGTTIN`), so an interactive re-execution stays a plain spawn in the caller's
-group. Importing one leaf does not make
+passes an abort signal and `stop: { target: 'leader', signal: 'SIGTERM', graceMs }`. It records the
+pid in `onLeaderStarted({ pid })`, which runs once right after the leader exists (a throw stops the
+command with that error), reads the exit code and signal in `onLeaderSettled` before the pipes
+drain, and reads stderr through `onOutput` or `capture` with `maxOutputBytes`. `drainTimeoutMs`
+bounds how long the output pipes may stay open after the leader exited: a holder that left the
+group with `setsid` keeps them open, and without the option the command waits for it until
+`timeoutMs` or the signal; with it the command ends with `COMMAND_CLEANUP` (a holder inside the
+group is already stopped by `descendants`). A worker whose whole group must stop on abort is the
+default `target: 'group'`. A child that inherits the caller's terminal is outside this
+capability: every command runs in a group of its own, and a background group that reads the
+terminal is stopped by the kernel (`SIGTTIN`), so an interactive re-execution stays a plain
+spawn in the caller's group. Importing one leaf does not make
 installing the whole npm package smaller; choose a dependency after measuring packed size and its
 dependency closure.
 
@@ -22642,7 +22646,7 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `onLeaderStarted({ pid })` (once, after the leader exists), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
 | `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |

package/llms.txt

@@ -56,7 +56,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 35.6 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 36.2 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 2.8 KB
 
 ## Upgrading slices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.105.1",
+  "version": "0.105.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",