stitchkit 0.111.0 → 0.111.2

package/CHANGELOG.md

@@ -15,6 +15,25 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.111.2] - 2026-10-17
+
+### Added
+
+- `stitchkit/process`: `streamNativeCommand` starts a command like `runNativeCommand` and returns its stdout and stderr as `ReadableStream<Uint8Array>` while it runs, with `result` and `stop()`. It uses the same owner, so a stream keeps the group ownership, the `stop` policy, the bounds and every group-stop fix of `runNativeCommand`; a slow reader slows the child through pipe backpressure. The `stitchkit/process` surface ceiling rises from 12 to 15 for `streamNativeCommand` and its two types.
+
+## [0.111.1] - 2026-10-17
+
+### Fixed
+
+- `stitchkit/server` — **an open contract stream keeps a constant number of objects however many frames it sends.** Each frame raced the source against a promise that lived as long as the stream, so every frame left a reaction and the frame itself retained until the stream ended; a subscription sending a frame a second grew by about 1.6 MB a minute. The stream now waits for each frame through a listener it removes itself. A source that never has to wait is also stopped at the stream's `lifetimeMs`, which it used to outlive. → ADR 0264
+  **Affects:** `stitchkit/server` createServer, createHandler, implement
+- `stitchkit/voice` — **`SpeechQueue` no longer keeps a reaction and the spoken clip for every sentence it has said.** → ADR 0264
+  **Affects:** `stitchkit/voice` SpeechQueue
+- `stitchkit/tools/mcp` — **`createMcpHandler` no longer keeps the authenticated principal of every request it has answered until it is closed.** → ADR 0264
+  **Affects:** `stitchkit/tools/mcp` createMcpHandler
+- `stitchkit/application/grammy` — **the update gate follows grammY's polling signal once instead of adding a listener on every `getUpdates`.** → ADR 0264
+  **Affects:** `stitchkit/application/grammy` behaviour
+
 ## [0.111.0] - 2026-10-17
 
 ### ⚠️ Breaking changes

package/dist/application/grammy-update-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammy-update-admission.d.ts","sourceRoot":"","sources":["../../src/application/grammy-update-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,IAAI,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAAG,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAsDD,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAmDvF"}
+{"version":3,"file":"grammy-update-admission.d.ts","sourceRoot":"","sources":["../../src/application/grammy-update-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,IAAI,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAAG,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAiED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAmDvF"}

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

@@ -21,7 +21,7 @@ import {
 import"../../index-zrtrjkbf.js";
 import {
   readBoundedBody2
-} from "../../index-qndsr7f0.js";
+} from "../../index-5efrpfmj.js";
 import {
   MAX_TIMER_MS
 } from "../../index-eemvahkc.js";

package/dist/entrypoints/application/grammy.js

@@ -15,7 +15,7 @@ function batchSize(result) {
 function abortError() {
   return new DOMException("Telegram polling stopped", "AbortError");
 }
-function untilAborted(signal) {
+function untilNoLongerAdmitted(signal) {
   return new Promise((_, reject) => {
     if (signal.aborted)
       reject(abortError());
@@ -29,10 +29,19 @@ async function admitted(admission, signal) {
   } catch {
     if (signal.aborted)
       throw abortError();
-    return untilAborted(signal);
+    return untilNoLongerAdmitted(signal);
   }
 }
+var followers = new WeakMap;
 function followed(signal) {
+  const known = followers.get(signal);
+  if (known)
+    return known;
+  const follower = follow(signal);
+  followers.set(signal, follower);
+  return follower;
+}
+function follow(signal) {
   const controller = new AbortController;
   if (signal.aborted)
     controller.abort(abortError());

package/dist/entrypoints/cli/publish.js

@@ -15,7 +15,7 @@ import {
   gzipCliAsset,
   decodeCliAsset,
   compareCliVersions2
-} from "../../index-kdnfe0sr.js";
+} from "../../index-erv5shjq.js";
 import {
   withExclusiveLock2
 } from "../../index-w9mqgnz9.js";

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-syzngt7v.js";
+} from "../index-v2eyj2ws.js";
 import"../index-fynr93w4.js";
 import"../index-ct75c3at.js";
 import"../index-q6crhe1n.js";
@@ -40,7 +40,7 @@ import {
   checkCliUpdate2,
   applyCliUpdate2,
   rollbackCliUpdate2
-} from "../index-kdnfe0sr.js";
+} from "../index-erv5shjq.js";
 import {
   writeFileAtomicSync2
 } from "../index-07dcf2yn.js";

package/dist/entrypoints/http.js

@@ -14,13 +14,13 @@ import {
   createUrlBuilder2,
   createUrlBuilders2,
   createScopedUrlBuilders2
-} from "../index-1y0arq4z.js";
+} from "../index-c5at3ykd.js";
 import {
   ApiError2
 } from "../index-kfjkb396.js";
 import {
   readBoundedBody2
-} from "../index-qndsr7f0.js";
+} from "../index-5efrpfmj.js";
 export {
   ApiError2 as ApiError,
   contractEndpointMatchers2 as contractEndpointMatchers,

package/dist/entrypoints/index.js

@@ -71,7 +71,7 @@ import {
   createUrlBuilder2,
   createUrlBuilders2,
   createScopedUrlBuilders2
-} from "../index-1y0arq4z.js";
+} from "../index-c5at3ykd.js";
 import {
   createRetainedTopics2,
   createRealtimeClientWithPeer,
@@ -85,7 +85,7 @@ import {
 } from "../index-kfjkb396.js";
 import {
   readBoundedBody2
-} from "../index-qndsr7f0.js";
+} from "../index-5efrpfmj.js";
 import {
   sleep
 } from "../index-eemvahkc.js";

package/dist/entrypoints/node.js

@@ -23,7 +23,7 @@ import {
   createSocketIOServer2,
   UnixClientTransportError2,
   createUnixClientTransport2
-} from "../index-krng2a5j.js";
+} from "../index-2qymcsq2.js";
 import {
   bindRealtimeServer2
 } from "../index-xmgjtkvr.js";

package/dist/entrypoints/process.d.ts

@@ -2,4 +2,5 @@
 export { observeProcessInstance, type ProcessInstance, type ProcessInstanceObservation, ProcessInstanceSchema, type ProcessOwnerEvidence, probeProcessOwner, } from '../internal/process-instance.js';
 export { runNativeCommand } from '../process/command.js';
 export { NativeCommandError, type NativeCommandOptions, type NativeCommandResult, type NativeCommandSettlement, type NativeCommandStopPolicy, } from '../process/contract.js';
+export { type NativeCommandStream, type NativeCommandStreamOptions, streamNativeCommand, } from '../process/stream.js';
 //# sourceMappingURL=process.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/entrypoints/process.js

@@ -10,14 +10,89 @@ import {
 import {
   startNativeCommand
 } from "../index-7r4knwf8.js";
+import {
+  untilAborted
+} from "../index-a5qr2rj6.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;
 }
+// src/process/stream.ts
+function streamNativeCommand(input) {
+  for (const owned of ["capture", "onOutput", "stdio"])
+    if (owned in input)
+      throw new TypeError(`streamNativeCommand owns ${owned}`);
+  const channels = { stdout: channel(), stderr: channel() };
+  const owner = startNativeCommand({
+    ...input,
+    onOutput: async (bytes, name, signal) => {
+      await channels[name].push(Uint8Array.from(bytes), signal);
+    }
+  });
+  owner.result.then(() => {
+    channels.stdout.close();
+    channels.stderr.close();
+  }, (error) => {
+    channels.stdout.fail(error);
+    channels.stderr.fail(error);
+  });
+  return {
+    stdout: channels.stdout.stream,
+    stderr: channels.stderr.stream,
+    result: owner.result,
+    stop: () => owner.stop()
+  };
+}
+var QUEUED_BYTES = 1024 * 1024;
+function channel() {
+  let controller;
+  let cancelled = false;
+  let settled = false;
+  let resume = Promise.withResolvers();
+  const stream = new ReadableStream({
+    start(c) {
+      controller = c;
+    },
+    pull() {
+      resume.resolve();
+    },
+    cancel() {
+      cancelled = true;
+      resume.resolve();
+    }
+  }, new ByteLengthQueuingStrategy({ highWaterMark: QUEUED_BYTES }));
+  return {
+    stream,
+    async push(bytes, signal) {
+      if (cancelled || settled)
+        return;
+      controller.enqueue(bytes);
+      while (!cancelled && !signal.aborted && (controller.desiredSize ?? 0) <= 0) {
+        resume = Promise.withResolvers();
+        await untilAborted(resume.promise, signal).catch(() => {
+          return;
+        });
+      }
+    },
+    close() {
+      if (cancelled || settled)
+        return;
+      settled = true;
+      controller.close();
+    },
+    fail(error) {
+      if (cancelled || settled)
+        return;
+      settled = true;
+      controller.error(error);
+    }
+  };
+}
 export {
   NativeCommandError2 as NativeCommandError,
   ProcessInstanceSchema2 as ProcessInstanceSchema,
   observeProcessInstance2 as observeProcessInstance,
   probeProcessOwner2 as probeProcessOwner,
-  runNativeCommand
+  runNativeCommand,
+  streamNativeCommand
 };

package/dist/entrypoints/remote.js

@@ -4,7 +4,7 @@ import"../index-p6apg0jg.js";
 import {
   endpointHasArguments,
   createClient2
-} from "../index-1y0arq4z.js";
+} from "../index-c5at3ykd.js";
 import {
   ApiError2
 } from "../index-kfjkb396.js";

package/dist/entrypoints/server.js

@@ -49,7 +49,7 @@ import {
   socketIoLane2,
   UnixClientTransportError2,
   createUnixClientTransport2
-} from "../index-krng2a5j.js";
+} from "../index-2qymcsq2.js";
 import {
   createFileStateStore2
 } from "../index-nx49x0tw.js";
@@ -86,7 +86,7 @@ import"../index-1bx1xv1k.js";
 import {
   readBoundedChunks,
   concatChunks
-} from "../index-qndsr7f0.js";
+} from "../index-5efrpfmj.js";
 import {
   assertPositiveSafeInteger
 } from "../index-0s4xebbg.js";

package/dist/entrypoints/telegram.js

@@ -26,15 +26,15 @@ import {
   MAX_TIMER_MS,
   sleep
 } from "../index-eemvahkc.js";
-import {
-  untilAborted
-} from "../index-a5qr2rj6.js";
 import {
   assertPositiveSafeInteger
 } from "../index-0s4xebbg.js";
 import {
   BOT_TOKEN_SECRET
 } from "../index-sznqf8fx.js";
+import {
+  untilAborted
+} from "../index-a5qr2rj6.js";
 import {
   isRecord,
   transportResult

package/dist/entrypoints/testing.js

@@ -35,7 +35,7 @@ import"../index-fynr93w4.js";
 import {
   createClient2,
   createClients2
-} from "../index-1y0arq4z.js";
+} from "../index-c5at3ykd.js";
 import {
   assertPositiveSafeInteger
 } from "../index-0s4xebbg.js";

package/dist/entrypoints/tools/connections.js

@@ -16,7 +16,7 @@ import {
 import {
   readBoundedChunks,
   concatChunks
-} from "../../index-qndsr7f0.js";
+} from "../../index-5efrpfmj.js";
 import {
   MAX_TIMER_MS
 } from "../../index-eemvahkc.js";

package/dist/entrypoints/tools/mcp.js

@@ -20,7 +20,7 @@ import {
   createMcpHttpRoute2,
   createStdioMcpServer2,
   bindStdioProcessSignals2
-} from "../../index-s2eybn7b.js";
+} from "../../index-c5374vpt.js";
 import"../../index-0d8m0kee.js";
 import"../../index-636mggad.js";
 export {

package/dist/entrypoints/tools.js

@@ -60,7 +60,7 @@ import {
   createMcpHttpRoute2,
   createStdioMcpServer2,
   bindStdioProcessSignals2
-} from "../index-s2eybn7b.js";
+} from "../index-c5374vpt.js";
 import {
   AsyncOperationCancelResultSchema2,
   createAsyncOperationSnapshotSchema2,
@@ -74,7 +74,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-syzngt7v.js";
+} from "../index-v2eyj2ws.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2
@@ -97,12 +97,12 @@ import {
   fetchGuarded,
   fetchPinnedDocument,
   readCapped
-} from "../index-t65erk4z.js";
+} from "../index-cxpcdswt.js";
 import"../index-1bx1xv1k.js";
 import {
   readBoundedChunks,
   concatChunks
-} from "../index-qndsr7f0.js";
+} from "../index-5efrpfmj.js";
 import {
   assertPositiveSafeInteger
 } from "../index-0s4xebbg.js";

package/dist/entrypoints/voice.js

@@ -1,3 +1,7 @@
+import {
+  untilAborted
+} from "../index-a5qr2rj6.js";
+
 // src/voice/phases.ts
 var LIVE_VOICE_PHASES = [
   "opening",
@@ -99,10 +103,7 @@ class SpeechQueue {
   closed = false;
   cancelled = false;
   wake = null;
-  stop;
-  stopped = new Promise((resolve) => {
-    this.stop = resolve;
-  });
+  stopped = new AbortController;
   constructor(options) {
     this.options = options;
     const lookahead = options.lookahead ?? 1;
@@ -146,9 +147,16 @@ class SpeechQueue {
           this.release(outcome.value);
       });
     }
-    this.stop(CANCELLED);
+    this.stopped.abort();
     this.notify();
   }
+  async unlessStopped(pending) {
+    try {
+      return await untilAborted(pending, this.stopped.signal);
+    } catch {
+      return CANCELLED;
+    }
+  }
   notify() {
     this.wake?.();
   }
@@ -179,19 +187,18 @@ class SpeechQueue {
       }
       this.current = slot;
       try {
-        const prepared = await Promise.race([slot.result, this.stopped]);
+        const prepared = await this.unlessStopped(slot.result);
         if (prepared === CANCELLED)
           return;
         if (!prepared.ok) {
           this.report(prepared.error, slot.text);
           continue;
         }
+        if (this.cancelled)
+          return;
         this.playing = true;
         this.fill();
-        const played = await Promise.race([
-          settle(() => this.options.play(prepared.value, slot.controller.signal)),
-          this.stopped
-        ]);
+        const played = await this.unlessStopped(settle(() => this.options.play(prepared.value, slot.controller.signal)));
         if (played === CANCELLED)
           return;
         if (!played.ok)

package/dist/{index-krng2a5j.js → index-2qymcsq2.js}

@@ -31,10 +31,7 @@ import {
   readBoundedChunks,
   concatChunks,
   readBoundedBody2
-} from "./index-qndsr7f0.js";
-import {
-  abortReason
-} from "./index-a5qr2rj6.js";
+} from "./index-5efrpfmj.js";
 import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";
@@ -62,6 +59,10 @@ import {
   getClientInfo2,
   parseQueryParams
 } from "./index-kw1ws0cs.js";
+import {
+  abortReason,
+  untilAborted
+} from "./index-a5qr2rj6.js";
 import {
   isUnsafeKey,
   safeJsonParse
@@ -1001,15 +1002,6 @@ function encodedBytes(value, format) {
 `;
   return new TextEncoder().encode(framing).byteLength;
 }
-function waitForAbort(signal) {
-  return new Promise((_resolve, reject) => {
-    const rejectAborted = () => reject(signal.reason ?? new Error("Stream aborted"));
-    if (signal.aborted)
-      rejectAborted();
-    else
-      signal.addEventListener("abort", rejectAborted, { once: true });
-  });
-}
 function contractStreamResponse(request, context, source, descriptor, operationAbort) {
   const format = descriptor.format ?? "ndjson";
   const maxFrameBytes = descriptor.maxFrameBytes ?? DEFAULT_CONTRACT_STREAM_FRAME_BYTES2;
@@ -1048,12 +1040,11 @@ function contractStreamResponse(request, context, source, descriptor, operationA
   const frames = async function* () {
     if (closing)
       return;
-    const aborted = waitForAbort(operationAbort.signal);
     let terminalSeen = descriptor.terminal === undefined;
     try {
       for (;; ) {
         pendingNext = Promise.resolve(iterator.next());
-        const next = await Promise.race([pendingNext, aborted]);
+        const next = await untilAborted(pendingNext, operationAbort.signal);
         if (next.done)
           break;
         const parsed = descriptor.item.safeParse(next.value);

package/dist/{index-s2eybn7b.js → index-c5374vpt.js}

@@ -36,6 +36,9 @@ import {
   runWithRequestContext2,
   getRequestContext2
 } from "./index-r6v4mc67.js";
+import {
+  untilAborted
+} from "./index-a5qr2rj6.js";
 import {
   AppError2
 } from "./index-j9gxbztg.js";
@@ -971,10 +974,7 @@ function createMcpHandler2(config) {
   const buildPrepared = prepareStaticSurface(config);
   const authByCarrier = new WeakMap;
   let closed = false;
-  let resolveClosed;
-  const closedSignal = new Promise((resolve) => {
-    resolveClosed = resolve;
-  });
+  const closing = new AbortController;
   const sdkHandler = createSdkMcpHandler(({ authInfo }) => {
     const resolved = authInfo ? authByCarrier.get(authInfo) : undefined;
     if (!resolved) {
@@ -1011,10 +1011,11 @@ function createMcpHandler2(config) {
       const originRejection = originValidationResponse(request, [...allowedOrigins]);
       if (originRejection)
         return observeRejection(request, originRejection);
-      const auth = await Promise.race([
-        Promise.resolve(config.auth(request)),
-        closedSignal.then(() => null)
-      ]);
+      const auth = await untilAborted(Promise.resolve(config.auth(request)), closing.signal).catch((error) => {
+        if (closing.signal.aborted)
+          return null;
+        throw error;
+      });
       if (closed) {
         return observeRejection(request, jsonRpcError(-32000, "MCP handler is closed", 503));
       }
@@ -1036,7 +1037,7 @@ function createMcpHandler2(config) {
       if (closed)
         return;
       closed = true;
-      resolveClosed?.();
+      closing.abort();
       await sdkHandler.close();
     }
   };

package/dist/{index-t65erk4z.js → index-cxpcdswt.js}

@@ -3,7 +3,7 @@ import {
 } from "./index-b0kddvzw.js";
 import {
   readBoundedChunks
-} from "./index-qndsr7f0.js";
+} from "./index-5efrpfmj.js";
 
 // src/internal/secure-fetch.ts
 import { lookup } from "node:dns/promises";

package/dist/{index-kdnfe0sr.js → index-erv5shjq.js}

@@ -5,7 +5,7 @@ import {
   fetchGuarded,
   PrivateAddressRefusal,
   readCapped
-} from "./index-t65erk4z.js";
+} from "./index-cxpcdswt.js";
 import {
   writeFileAtomicSync2
 } from "./index-07dcf2yn.js";

package/dist/{index-syzngt7v.js → index-v2eyj2ws.js}

@@ -26,7 +26,7 @@ import {
 import {
   fetchGuarded,
   readCapped
-} from "./index-t65erk4z.js";
+} from "./index-cxpcdswt.js";
 import {
   isWithinDir2
 } from "./index-5cc6r990.js";

package/dist/process/stream.d.ts

@@ -0,0 +1,27 @@
+import type { NativeCommandOptions, NativeCommandResult } from './contract.js';
+/** Options the stream owns: its readers are the capture, the sink and the pipes. */
+export type NativeCommandStreamOptions = Omit<NativeCommandOptions, 'capture' | 'onOutput' | 'stdio'>;
+/** A started command whose output is read as it appears. */
+export interface NativeCommandStream {
+    /** The leader's stdout; closes once the command finished and every byte was queued. */
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    /**
+     * Settles like `runNativeCommand` once the command ended and both streams were read to the end
+     * or cancelled: a stream nobody reads holds the child back, and with it this result. Its
+     * `stdout` and `stderr` are empty, the streams hold the bytes.
+     */
+    readonly result: Promise<NativeCommandResult>;
+    /** Stops the command with its stop policy and resolves once its resources are proven closed. */
+    stop(): Promise<void>;
+}
+/**
+ * Starts one command directly (no shell) like `runNativeCommand`, with the same group ownership,
+ * stop policy and bounds, and hands its output over as `ReadableStream`s instead of buffering it
+ * for the end. A slow reader slows the child (pipe backpressure); a cancelled stream drops what
+ * follows without stopping the command. When the command fails or is stopped, both streams error and
+ * the bytes still queued are dropped. A stream nobody reads holds the child back
+ * once it queued 1 MiB, so read large outputs concurrently or cancel the stream.
+ */
+export declare function streamNativeCommand(input: NativeCommandStreamOptions): NativeCommandStream;
+//# sourceMappingURL=stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/process/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE5E,oFAAoF;AACpF,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,oBAAoB,EACpB,SAAS,GAAG,UAAU,GAAG,OAAO,CACjC,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,gGAAgG;IAChG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,0BAA0B,GAAG,mBAAmB,CA0B1F"}

package/dist/server/contract-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-stream.d.ts","sourceRoot":"","sources":["../../src/server/contract-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAUnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAiB/C,gEAAgE;AAChE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,UAAU,EAAE,wBAAwB,EACpC,cAAc,EAAE,eAAe,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAgHnB"}
+{"version":3,"file":"contract-stream.d.ts","sourceRoot":"","sources":["../../src/server/contract-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAWnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAS/C,gEAAgE;AAChE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,UAAU,EAAE,wBAAwB,EACpC,cAAc,EAAE,eAAe,GAC9B,OAAO,CAAC,QAAQ,CAAC,CA+GnB"}

package/dist/tools/mcp/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/handler.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,WAAW,CAAC;AAEnB,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC7D,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;KACpB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,EACL,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;AAElE,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAgFD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EACL,KAAK,CAAC,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,EAC/D,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,cAAc,CAkF5D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,QAAQ,CAMX"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/handler.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,WAAW,CAAC;AAEnB,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC7D,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;KACpB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,EACL,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;AAElE,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAgFD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EACL,KAAK,CAAC,SAAS,SAAS,kBAAkB,GAAG,kBAAkB,EAC/D,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,cAAc,CAoF5D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,QAAQ,CAMX"}

package/dist/voice/speech-queue.d.ts

@@ -21,7 +21,6 @@ export declare class SpeechQueue<Prepared> {
     private closed;
     private cancelled;
     private wake;
-    private stop;
     private readonly stopped;
     constructor(options: SpeechQueueOptions<Prepared>);
     get isCancelled(): boolean;
@@ -32,6 +31,12 @@ export declare class SpeechQueue<Prepared> {
     close(): void;
     /** Interrupted: abort the sentence playing and every synthesis, drop the rest. */
     cancel(): void;
+    /**
+     * `pending`, or `CANCELLED` once the queue is cancelled. The wait owns its listener and
+     * releases it when `pending` settles: a promise shared by every sentence would keep one
+     * reaction per sentence for as long as the queue lives. `pending` never rejects.
+     */
+    private unlessStopped;
     private notify;
     /** Start synthesis up to the lookahead: the sentence playing or next, plus `lookahead`. */
     private fill;

package/dist/voice/speech-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"speech-queue.d.ts","sourceRoot":"","sources":["../../src/voice/speech-queue.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,oEAAoE;IACpE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,kFAAkF;IAClF,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACxC;AAqBD,qBAAa,WAAW,CAAC,QAAQ;IAenB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAdpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,YAA6B,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAOjE;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvB;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAGZ;IAED,kFAAkF;IAClF,MAAM,IAAI,IAAI,CAgBb;IAED,OAAO,CAAC,MAAM;IAId,2FAA2F;IAC3F,OAAO,CAAC,IAAI;YAaE,GAAG;IAmCjB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;CAOhB"}
+{"version":3,"file":"speech-queue.d.ts","sourceRoot":"","sources":["../../src/voice/speech-queue.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,oEAAoE;IACpE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,kFAAkF;IAClF,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACxC;AAqBD,qBAAa,WAAW,CAAC,QAAQ;IAYnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAXpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,YAA6B,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAOjE;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvB;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAGZ;IAED,kFAAkF;IAClF,MAAM,IAAI,IAAI,CAgBb;IAED;;;;OAIG;YACW,aAAa;IAQ3B,OAAO,CAAC,MAAM;IAId,2FAA2F;IAC3F,OAAO,CAAC,IAAI;YAaE,GAAG;IAoCjB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;CAOhB"}

package/llms/process.2.txt

@@ -0,0 +1,32 @@
+# stitchkit/process — stitchkit docs slice, part 2 of 2
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/process.txt`: Guide: Native IO  (docs/guide/native-io.md)
+- `llms/process.2.txt`: API reference: `stitchkit/process`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/process`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/process`
+
+Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `streamNativeCommand` | function | starts a command under the same group ownership, stop policy and bounds as `runNativeCommand` and returns `stdout` / `stderr` as `ReadableStream<Uint8Array>`, `result` and `stop()`; a slow reader slows the child, a cancelled stream drops its bytes, a failed command errors both streams |
+| `NativeCommandStream` | type | what `streamNativeCommand` returns: `stdout`, `stderr`, `result` (its buffers are empty) and `stop()` |
+| `NativeCommandStreamOptions` | type | `NativeCommandOptions` without `capture`, `onOutput` and `stdio`, which the streams own |
+| `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'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `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; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
+
+| `NativeCommandSettlement` | type | `exit` (the leader ended on its own), `stopped` (the command was stopped and the leader's exit after the stop observed: the stop's `cause` with `exitCode`/`signal`) or `error` (no exit observed), including synchronous native launch failure; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal; schema/pre-abort refusal creates no settlement obligation |
+| `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
+| `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
+| `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |

package/llms/process.txt

@@ -1,9 +1,12 @@
-# stitchkit/process — stitchkit docs slice
+# stitchkit/process — stitchkit docs slice, part 1 of 2
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/process.2.txt`.
 
-Contains: Guide: Native IO  (docs/guide/native-io.md) · API reference: `stitchkit/process`  (docs/api/reference.md)
+Parts of this slice:
+- `llms/process.txt`: Guide: Native IO  (docs/guide/native-io.md)
+- `llms/process.2.txt`: API reference: `stitchkit/process`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Native IO  (docs/guide/native-io.md)
@@ -147,6 +150,27 @@ await runNativeCommand({
 })
 ```
 
+To read output as it appears, use `streamNativeCommand`: the same owner, group ownership, `stop`
+policy and bounds, with the output as `ReadableStream<Uint8Array>`.
+
+```ts
+import { streamNativeCommand } from 'stitchkit/process'
+
+const lifetime = new AbortController()
+const command = streamNativeCommand({
+  executable: '/usr/bin/tail', args: ['-f', '/var/log/app.log'], signal: lifetime.signal,
+})
+void command.stderr.cancel() // not interested: dropped, the command keeps running
+for await (const bytes of command.stdout) handle(bytes) // a slow reader slows the child
+await command.result // settles like `runNativeCommand`; `stop()` ends the group and waits for it
+```
+
+The streams own `capture`, `onOutput` and `stdio`; passing one is refused. Each stream queues up to 1 MiB, so
+a small output can be read in any order, even after `result`; past that an unread stream fills its pipe
+and holds the command, and its `result`, until the signal or `timeoutMs`, so read large outputs
+concurrently or cancel the stream you ignore. Cancelling a stream drops its later bytes and leaves the command running. When the
+command fails or is stopped, both streams error and the bytes still queued are dropped.
+
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
 range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
@@ -698,24 +722,3 @@ A sandbox admission slot is released once a direct command's pipes have closed a
 A `COMMAND_CLEANUP` outcome means the death of its group was not proven, so the slot stays
 occupied, `stop` keeps rejecting with the cleanup error, and the sandbox session is recreated to
 recover.
-
-==============================================================================
-# API reference: `stitchkit/process`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit/process`
-
-Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
-
-| 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'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `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; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
-
-| `NativeCommandSettlement` | type | `exit` (the leader ended on its own), `stopped` (the command was stopped and the leader's exit after the stop observed: the stop's `cause` with `exitCode`/`signal`) or `error` (no exit observed), including synchronous native launch failure; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal; schema/pre-abort refusal creates no settlement obligation |
-| `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
-| `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
-| `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |

package/llms-full.txt

@@ -8586,6 +8586,27 @@ await runNativeCommand({
 })
 ```
 
+To read output as it appears, use `streamNativeCommand`: the same owner, group ownership, `stop`
+policy and bounds, with the output as `ReadableStream<Uint8Array>`.
+
+```ts
+import { streamNativeCommand } from 'stitchkit/process'
+
+const lifetime = new AbortController()
+const command = streamNativeCommand({
+  executable: '/usr/bin/tail', args: ['-f', '/var/log/app.log'], signal: lifetime.signal,
+})
+void command.stderr.cancel() // not interested: dropped, the command keeps running
+for await (const bytes of command.stdout) handle(bytes) // a slow reader slows the child
+await command.result // settles like `runNativeCommand`; `stop()` ends the group and waits for it
+```
+
+The streams own `capture`, `onOutput` and `stdio`; passing one is refused. Each stream queues up to 1 MiB, so
+a small output can be read in any order, even after `result`; past that an unread stream fills its pipe
+and holds the command, and its `result`, until the signal or `timeoutMs`, so read large outputs
+concurrently or cancel the stream you ignore. Cancelling a stream drops its later bytes and leaves the command running. When the
+command fails or is stopped, both streams error and the bytes still queued are dropped.
+
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
 range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
@@ -23566,6 +23587,9 @@ 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 |
+| `streamNativeCommand` | function | starts a command under the same group ownership, stop policy and bounds as `runNativeCommand` and returns `stdout` / `stderr` as `ReadableStream<Uint8Array>`, `result` and `stop()`; a slow reader slows the child, a cancelled stream drops its bytes, a failed command errors both streams |
+| `NativeCommandStream` | type | what `streamNativeCommand` returns: `stdout`, `stderr`, `result` (its buffers are empty) and `stop()` |
+| `NativeCommandStreamOptions` | type | `NativeCommandOptions` without `capture`, `onOutput` and `stdio`, which the streams own |
 | `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'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `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 |

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) 45.8 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 43.7 KB → [llms/process.2.txt](llms/process.2.txt) 4.3 KB
 - **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 - **stitchkit/http**: [llms/http.txt](llms/http.txt) 0.9 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.111.0",
+  "version": "0.111.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",

package/dist/{index-qndsr7f0.js → index-5efrpfmj.js}

@@ -1,12 +1,12 @@
 import {
   chunksOf
 } from "./index-cjbn98zt.js";
-import {
-  abortReason
-} from "./index-a5qr2rj6.js";
 import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";
+import {
+  abortReason
+} from "./index-a5qr2rj6.js";
 
 // src/internal/bounded-body.ts
 async function readBoundedChunks(source, options) {