stitchkit 0.103.10 → 0.103.11

package/dist/process/launch.d.ts

@@ -0,0 +1,65 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type ParsedNativeCommandOptions } from './contract.js';
+/** A structural host launcher may supply pipes without importing Node ambient types. */
+export interface NativeCommandLaunchedProcess {
+    readonly pid?: number;
+    readonly exitCode: number | null;
+    readonly signalCode: string | null;
+    readonly stdout: NativeCommandLaunchedOutput;
+    readonly stderr: NativeCommandLaunchedOutput;
+    kill(signal: 'SIGKILL'): boolean;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit' | 'close', listener: (code: number | null, signal: string | null) => void): unknown;
+}
+interface NativeCommandLaunchedOutput {
+    readonly destroyed: boolean;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    destroy(): unknown;
+}
+/** Internal transport selection; application policy never enters the public command contract. */
+export interface NativeCommandLaunchDriver {
+    launch?: () => NativeCommandLaunchedProcess;
+    maxBufferedBytes?: number;
+    group?: boolean;
+    force?: boolean;
+    cleanupTimeoutMs?: number;
+    timeoutMs?: number;
+    closeTimeoutMs?: number;
+}
+/** Driver overrides retain the same finite, safe-integer budget admission. */
+export declare function nativeCommandBudgets(options: ParsedNativeCommandOptions, driver: NativeCommandLaunchDriver | undefined): {
+    cleanupTimeoutMs: number;
+    timeoutMs: number | undefined;
+};
+interface NativeCommandOwner {
+    result: Promise<unknown>;
+    stop(): Promise<void>;
+    terminate(): Promise<void>;
+}
+/** A launcher and its admission owner share the execution owner's shutdown barrier. */
+export declare function registerNativeCommandOwner(child: object, owner: NativeCommandOwner): void;
+export declare function nativeCommandOwner(child: object): NativeCommandOwner | undefined;
+/** Install every observation before starting stdin or invoking an admission callback. */
+export declare function launchNativeCommand(options: ParsedNativeCommandOptions, driver: NativeCommandLaunchDriver | undefined, onSpawn: ((child: ChildProcessWithoutNullStreams) => void) | undefined, onFailure: (error: Error) => void, onInputFailure: (error: Error) => void): {
+    child: NativeCommandLaunchedProcess;
+    stdout: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    stderr: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    leader: Promise<{
+        kind: "exit";
+        exitCode: number | null;
+        signal: string | null;
+    } | {
+        kind: "error";
+        cause: unknown;
+    }>;
+    closed: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    released: Promise<[boolean, ...boolean[]]>;
+    pendingHandles: Set<string>;
+    start(): void;
+    destroy(): void;
+};
+export {};
+//# sourceMappingURL=launch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/process/launch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,8BAA8B,EAAS,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,YAAY,CAAC;AAEpB,wFAAwF;AACxF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC9D,EAAE,CACA,KAAK,EAAE,MAAM,GAAG,OAAO,EACvB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAC7D,OAAO,CAAC;CACZ;AAED,UAAU,2BAA2B;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC;CACpB;AAED,iGAAiG;AACjG,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,4BAA4B,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,yBAAyB,GAAG,SAAS;;;EAY9C;AAED,UAAU,kBAAkB;IAC1B,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAGD,uFAAuF;AACvF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAEzF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEhF;AA4ED,yFAAyF;AACzF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,CAAC,GAAG,SAAS,EACtE,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EACjC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;;;;;;;;;;;;;kBAuBC,MAAM,GAAG,IAAI;gBAAU,MAAM,GAAG,IAAI;;;;;;EA0D5E"}

package/dist/process/leader-settlement.d.ts

@@ -1,4 +1,6 @@
 import type { NativeCommandSettlement, ParsedNativeCommandOptions } from './contract.js';
+/** An internal caller may bound drain/close after leader settlement without changing generic drain. */
+export declare function createLeaderCloseDeadline(leader: Promise<NativeCommandSettlement>, timeoutMs: number | undefined, controller: AbortController): () => void;
 /** One bounded external resource settlement, shared by observed exit and terminal failure. */
 export declare function createLeaderSettlement(options: ParsedNativeCommandOptions, signal: AbortSignal): (event: NativeCommandSettlement) => Promise<void>;
 //# sourceMappingURL=leader-settlement.d.ts.map

package/dist/process/leader-settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"leader-settlement.d.ts","sourceRoot":"","sources":["../../src/process/leader-settlement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAGtF,8FAA8F;AAC9F,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,WAAW,WAGJ,uBAAuB,KAAG,OAAO,CAAC,IAAI,CAAC,CA+BvD"}
+{"version":3,"file":"leader-settlement.d.ts","sourceRoot":"","sources":["../../src/process/leader-settlement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAGtF,uGAAuG;AACvG,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,CAAC,uBAAuB,CAAC,EACxC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,eAAe,cAmB5B;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,WAAW,WAGJ,uBAAuB,KAAG,OAAO,CAAC,IAAI,CAAC,CAmCvD"}

package/dist/process/start-failure.d.ts

@@ -0,0 +1,7 @@
+import { type NativeCommandSettlement } from './contract.js';
+/** A failed native admission still owns one bounded external-resource settlement. */
+export declare function failedCommandStart(cause: unknown, settle: (event: NativeCommandSettlement) => Promise<void>): {
+    result: Promise<never>;
+    stop(): Promise<void>;
+};
+//# sourceMappingURL=start-failure.d.ts.map

package/dist/process/start-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-failure.d.ts","sourceRoot":"","sources":["../../src/process/start-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG9E,qFAAqF;AACrF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC;;;EAyB1D"}

package/llms/agent-runtime.txt

@@ -19,7 +19,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-09-28 18:39 +07:00
+updated: 2026-10-02 16:28 +07:00
 ---
 
 # Agent application runtime
@@ -376,6 +376,12 @@ second host executable, so Windows kills the direct child, destroys retained pip
 deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
 `cancelled` without spawning.
 
+Coding commands compose the shared native execution owner. Artifact retention and UTF-8
+previews remain coding-tool policy; normal leader exit still forcibly stops remaining POSIX
+group members before draining. A structural sandbox launcher uses the same settlement owner
+with a finite output queue. Sandbox shutdown waits for actual owned completion and surfaces
+cleanup refusal rather than treating it as successful teardown.
+
 One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
 concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
 new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;

package/llms/process.txt

@@ -15,7 +15,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-02 00:37 +07:00
+updated: 2026-10-02 16:28 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -131,6 +131,32 @@ await runNativeCommand({
 означает пустой environment; `ambient` явно разрешает наследование. Cwd/executable policy остаётся
 приложению; этот primitive запускает native executable и сам не создаёт shell.
 
+Машинная классификация limit error использует `NativeCommandError.reason`: `deadline` при
+истечении собственного `timeoutMs`, `output-budget` при превышении суммарных bytes stdout+stderr
+в capture или streaming. Оба случая сохраняют `code: 'COMMAND_LIMIT'`; `message` служит
+диагностике, не протоколу. У `COMMAND_UNAVAILABLE` и `COMMAND_CLEANUP` reason отсутствует;
+caller abort и sink failure сохраняют исходную ошибку. При cleanup failure первоначальный
+limit вместе с reason остаётся внутри `AggregateError` cause.
+
+```ts
+import { NativeCommandError } from 'stitchkit/process'
+
+try {
+  await runNativeCommand({ executable: '/usr/bin/git', args: ['status'], timeoutMs: 5000 })
+} catch (error) {
+  if (error instanceof NativeCommandError && error.code === 'COMMAND_LIMIT') {
+    if (error.reason === 'deadline') console.error('Command timed out')
+    if (error.reason === 'output-budget') console.error('Command produced too many bytes')
+  }
+  throw error
+}
+```
+
+Конструктор сохраняет вызов `new NativeCommandError(code, message, { cause })` и принимает
+`{ cause, reason: 'deadline' | 'output-budget' }` только для `COMMAND_LIMIT`. Owner всегда
+заполняет reason для собственных limits. Созданная вызывающей стороной ошибка без reason
+не получает выдуманную причину из текста; её reason остаётся `undefined`.
+
 Вывод читается с backpressure отдельно для stdout/stderr: один выполняющийся sink на канал плюс
 bounded native Readable buffer; накопления всей истории при streaming нет. Callback получает
 lifetime signal. Abort освобождает ожидание даже игнорирующего signal callback, но не способен
@@ -164,7 +190,11 @@ packed размера и dependency closure.
 close. A resource owner can stop its external scope there, allowing pipe drain to complete.
 The callback runs once: `event.kind === 'exit'` carries observed `exitCode`/`signal`; a terminal
 failure uses `kind: 'error'` and preserves its cause. Unavailable executables, output sink
-failure and caller cancellation settle through the same owner. `cleanupTimeoutMs` bounds
+failure and caller cancellation settle through the same owner. Synchronous native launch
+failures such as `E2BIG` also return a rejected result after this bounded settlement;
+schema-invalid and already-aborted inputs refuse before native ownership and do not invoke
+the hook. A failing hook preserves both the initial launch error and cleanup cause.
+`cleanupTimeoutMs` bounds
 the callback after settlement starts; it never becomes a deadline for signal-only execution.
 Honor the settlement signal; arbitrary user promises cannot be forcibly cancelled.
 
@@ -184,6 +214,14 @@ caller established: `matched`, `different-boot`, `reused-pid`, `pid-gone`, `lega
 `unavailable`. Missing/partial/denied evidence is not death. Supervisor tree fencing remains
 the caller's job; a PID lifetime is not proof that its whole workload stopped.
 
+Exclusive acquisition checks cancellation again before invoking the protected callback;
+an aborted acquisition releases its newly owned lock without starting the callback.
+Existing lock and reclaim-guard records are opened with nonblocking/no-follow flags,
+must be regular files with one link, and are capped at 16 KiB. Descriptor metadata must
+remain stable during the read. Unsafe records are not evidence of absence or permission
+to reclaim. This bounds local record reads; it does not make a hung remote-filesystem
+syscall interruptible or provide a snapshot against a hostile writer.
+
 An exclusive lock applies exact requested permissions through its creating descriptor,
 independent of umask. Default `0600` stays private. Shared `0640` requires a common group and
 traversable directories; another UID also needs directory write permission to reclaim a
@@ -234,9 +272,9 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
 | `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
 | `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
-| `NativeCommandError` | class | COMMAND_LIMIT, COMMAND_UNAVAILABLE or COMMAND_CLEANUP with internal cause |
+| `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 |
 
-| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal |
+| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`, 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

@@ -5119,7 +5119,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-09-28 18:39 +07:00
+updated: 2026-10-02 16:28 +07:00
 ---
 
 # Agent application runtime
@@ -5476,6 +5476,12 @@ second host executable, so Windows kills the direct child, destroys retained pip
 deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
 `cancelled` without spawning.
 
+Coding commands compose the shared native execution owner. Artifact retention and UTF-8
+previews remain coding-tool policy; normal leader exit still forcibly stops remaining POSIX
+group members before draining. A structural sandbox launcher uses the same settlement owner
+with a finite output queue. Sandbox shutdown waits for actual owned completion and surfaces
+cleanup refusal rather than treating it as successful teardown.
+
 One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
 concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
 new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;
@@ -8031,7 +8037,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-02 00:37 +07:00
+updated: 2026-10-02 16:28 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -8147,6 +8153,32 @@ await runNativeCommand({
 означает пустой environment; `ambient` явно разрешает наследование. Cwd/executable policy остаётся
 приложению; этот primitive запускает native executable и сам не создаёт shell.
 
+Машинная классификация limit error использует `NativeCommandError.reason`: `deadline` при
+истечении собственного `timeoutMs`, `output-budget` при превышении суммарных bytes stdout+stderr
+в capture или streaming. Оба случая сохраняют `code: 'COMMAND_LIMIT'`; `message` служит
+диагностике, не протоколу. У `COMMAND_UNAVAILABLE` и `COMMAND_CLEANUP` reason отсутствует;
+caller abort и sink failure сохраняют исходную ошибку. При cleanup failure первоначальный
+limit вместе с reason остаётся внутри `AggregateError` cause.
+
+```ts
+import { NativeCommandError } from 'stitchkit/process'
+
+try {
+  await runNativeCommand({ executable: '/usr/bin/git', args: ['status'], timeoutMs: 5000 })
+} catch (error) {
+  if (error instanceof NativeCommandError && error.code === 'COMMAND_LIMIT') {
+    if (error.reason === 'deadline') console.error('Command timed out')
+    if (error.reason === 'output-budget') console.error('Command produced too many bytes')
+  }
+  throw error
+}
+```
+
+Конструктор сохраняет вызов `new NativeCommandError(code, message, { cause })` и принимает
+`{ cause, reason: 'deadline' | 'output-budget' }` только для `COMMAND_LIMIT`. Owner всегда
+заполняет reason для собственных limits. Созданная вызывающей стороной ошибка без reason
+не получает выдуманную причину из текста; её reason остаётся `undefined`.
+
 Вывод читается с backpressure отдельно для stdout/stderr: один выполняющийся sink на канал плюс
 bounded native Readable buffer; накопления всей истории при streaming нет. Callback получает
 lifetime signal. Abort освобождает ожидание даже игнорирующего signal callback, но не способен
@@ -8180,7 +8212,11 @@ packed размера и dependency closure.
 close. A resource owner can stop its external scope there, allowing pipe drain to complete.
 The callback runs once: `event.kind === 'exit'` carries observed `exitCode`/`signal`; a terminal
 failure uses `kind: 'error'` and preserves its cause. Unavailable executables, output sink
-failure and caller cancellation settle through the same owner. `cleanupTimeoutMs` bounds
+failure and caller cancellation settle through the same owner. Synchronous native launch
+failures such as `E2BIG` also return a rejected result after this bounded settlement;
+schema-invalid and already-aborted inputs refuse before native ownership and do not invoke
+the hook. A failing hook preserves both the initial launch error and cleanup cause.
+`cleanupTimeoutMs` bounds
 the callback after settlement starts; it never becomes a deadline for signal-only execution.
 Honor the settlement signal; arbitrary user promises cannot be forcibly cancelled.
 
@@ -8200,6 +8236,14 @@ caller established: `matched`, `different-boot`, `reused-pid`, `pid-gone`, `lega
 `unavailable`. Missing/partial/denied evidence is not death. Supervisor tree fencing remains
 the caller's job; a PID lifetime is not proof that its whole workload stopped.
 
+Exclusive acquisition checks cancellation again before invoking the protected callback;
+an aborted acquisition releases its newly owned lock without starting the callback.
+Existing lock and reclaim-guard records are opened with nonblocking/no-follow flags,
+must be regular files with one link, and are capped at 16 KiB. Descriptor metadata must
+remain stable during the read. Unsafe records are not evidence of absence or permission
+to reclaim. This bounds local record reads; it does not make a hung remote-filesystem
+syscall interruptible or provide a snapshot against a hostile writer.
+
 An exclusive lock applies exact requested permissions through its creating descriptor,
 independent of umask. Default `0600` stays private. Shared `0640` requires a common group and
 traversable directories; another UID also needs directory write permission to reclaim a
@@ -21191,9 +21235,9 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
 | `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
 | `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
-| `NativeCommandError` | class | COMMAND_LIMIT, COMMAND_UNAVAILABLE or COMMAND_CLEANUP with internal cause |
+| `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 |
 
-| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal |
+| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`, 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.txt

@@ -23,7 +23,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.2 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.1 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 44.8 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.8 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.3 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 37.2 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.3 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 10.1 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 4.9 KB
@@ -55,7 +55,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **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) 1.8 KB
 - **stitchkit/agent-runtime/harness-tools**: [llms/agent-runtime-harness-tools.txt](llms/agent-runtime-harness-tools.txt) 1.3 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 15.9 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 18.6 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.103.10",
+  "version": "0.103.11",
   "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",
@@ -250,7 +250,7 @@
     "build": "bun ../../scripts/package-build-lock.ts -- bun run build:unlocked",
     "build:unlocked": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/entrypoints/bin/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-durability-port-standalone.mjs && bun scripts/check-declarations-strict.mjs",
     "dev": "bun run build:entrypoints -- --watch",
-    "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
+    "prepack": "bun ../../scripts/sync-package-readme.ts && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
     "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",

package/dist/index-6m6a9ty4.js

@@ -1,285 +0,0 @@
-import {
-  raceAbort
-} from "./index-mbnnw3f2.js";
-
-// src/process/contract.ts
-import { z } from "zod";
-var NativeCommandSettlementSchema = z.discriminatedUnion("kind", [
-  z.object({
-    kind: z.literal("exit"),
-    exitCode: z.number().int().nullable(),
-    signal: z.string().nullable()
-  }),
-  z.object({ kind: z.literal("error"), cause: z.unknown() })
-]);
-var NativeCommandOptionsSchema = z.strictObject({
-  executable: z.string().min(1),
-  args: z.array(z.string()).default([]),
-  cwd: z.string().optional(),
-  env: z.record(z.string(), z.string()).optional(),
-  envPolicy: z.enum(["declared-only", "ambient"]).default("declared-only"),
-  signal: z.custom((v) => v instanceof AbortSignal).optional(),
-  timeoutMs: z.number().int().positive().max(2147483647).optional(),
-  maxOutputBytes: z.number().int().positive().optional(),
-  capture: z.boolean().default(false),
-  stdin: z.custom((v) => v instanceof Uint8Array).optional(),
-  maxStdinBytes: z.number().int().positive().default(1024 * 1024),
-  onOutput: z.custom((v) => typeof v === "function").optional(),
-  onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
-  killGraceMs: z.number().int().nonnegative().max(1e4).default(100),
-  cleanupTimeoutMs: z.number().int().positive().max(30000).default(2000)
-}).superRefine((input, ctx) => {
-  if (!input.signal && input.timeoutMs === undefined)
-    ctx.addIssue({ code: "custom", message: "Declare a caller signal or a finite timeout" });
-  if (input.capture && input.maxOutputBytes === undefined)
-    ctx.addIssue({
-      code: "custom",
-      message: "Capture requires a finite combined output budget"
-    });
-  if (input.stdin && input.stdin.byteLength > input.maxStdinBytes)
-    ctx.addIssue({ code: "custom", message: "stdin exceeds maxStdinBytes" });
-});
-var NativeCommandResultSchema = z.object({
-  exitCode: z.number().int().nullable(),
-  signal: z.string().nullable(),
-  stdout: z.instanceof(Uint8Array),
-  stderr: z.instanceof(Uint8Array)
-});
-
-class NativeCommandError2 extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.code = code;
-    this.name = "NativeCommandError";
-  }
-}
-
-// src/process/command-owner.ts
-import { spawn } from "node:child_process";
-
-// src/process/group.ts
-function deniedOnDarwin(error) {
-  return process.platform === "darwin" && error instanceof Error && "code" in error && error.code === "EPERM";
-}
-function signalGroup(pid, signal) {
-  if (pid === undefined)
-    return;
-  try {
-    process.kill(-pid, signal);
-  } catch (error) {
-    if (!(error instanceof Error && ("code" in error) && error.code === "ESRCH"))
-      throw error;
-  }
-}
-function exists(pid) {
-  if (pid === undefined)
-    return false;
-  try {
-    process.kill(-pid, 0);
-    return true;
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ESRCH")
-      return false;
-    if (deniedOnDarwin(error))
-      return true;
-    throw error;
-  }
-}
-async function signalUntilSettled(pid, signal, deadline) {
-  for (;; ) {
-    try {
-      signalGroup(pid, signal);
-      return;
-    } catch (error) {
-      if (!deniedOnDarwin(error) || Date.now() >= deadline)
-        throw error;
-      await new Promise((resolve) => setTimeout(resolve, Math.min(10, deadline - Date.now())));
-    }
-  }
-}
-async function stopCommandGroup(pid, graceMs, cleanupTimeoutMs = 2000) {
-  const deadline = Date.now() + graceMs + cleanupTimeoutMs;
-  await signalUntilSettled(pid, "SIGTERM", deadline);
-  const until = Date.now() + graceMs;
-  while (Date.now() < until && exists(pid))
-    await new Promise((resolve) => setTimeout(resolve, Math.min(10, until - Date.now())));
-  await signalUntilSettled(pid, "SIGKILL", deadline);
-}
-function commandCleanupError(cause) {
-  return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
-    cause
-  });
-}
-function waitForCommandClose(closed, timeoutMs) {
-  return raceAbort(closed, AbortSignal.timeout(timeoutMs));
-}
-
-// src/process/leader-settlement.ts
-function createLeaderSettlement(options, signal) {
-  let pending;
-  return (event) => {
-    if (pending)
-      return pending;
-    pending = (async () => {
-      if (!options.onLeaderSettled)
-        return;
-      const controller = new AbortController;
-      const timer = setTimeout(() => controller.abort(new Error("Leader settlement deadline exceeded")), options.cleanupTimeoutMs);
-      const abort = () => controller.abort(signal.reason);
-      if (!signal.aborted)
-        signal.addEventListener("abort", abort, { once: true });
-      try {
-        await raceAbort(Promise.resolve(options.onLeaderSettled(event, controller.signal)), controller.signal);
-      } catch (cause) {
-        if (signal.aborted && cause === signal.reason)
-          throw cause;
-        throw commandCleanupError(new AggregateError([event, cause], "Leader settlement failed"));
-      } finally {
-        clearTimeout(timer);
-        signal.removeEventListener("abort", abort);
-        controller.abort(new Error("Leader settlement completed"));
-      }
-    })();
-    pending.catch(() => {
-      return;
-    });
-    return pending;
-  };
-}
-
-// src/process/command-owner.ts
-function startNativeCommand(input, onSpawn) {
-  const options = NativeCommandOptionsSchema.parse(input);
-  options.signal?.throwIfAborted();
-  if (process.platform === "win32")
-    throw new NativeCommandError2("COMMAND_UNAVAILABLE", "POSIX process groups are required");
-  const controller = new AbortController;
-  const abort = () => controller.abort(options.signal?.reason);
-  options.signal?.addEventListener("abort", abort, { once: true });
-  if (options.signal?.aborted)
-    abort();
-  const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(new NativeCommandError2("COMMAND_LIMIT", "Command deadline exceeded")), options.timeoutMs);
-  let child;
-  try {
-    child = spawn(options.executable, options.args, {
-      cwd: options.cwd,
-      env: options.envPolicy === "ambient" ? { ...process.env, ...options.env } : options.env ?? {},
-      detached: true,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-  } catch (cause) {
-    if (timer !== undefined)
-      clearTimeout(timer);
-    options.signal?.removeEventListener("abort", abort);
-    throw new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", { cause });
-  }
-  const stdout = [];
-  const stderr = [];
-  let total = 0;
-  let finished = false;
-  let spawnFailure;
-  const settle = createLeaderSettlement(options, controller.signal);
-  const leader = new Promise((resolve) => {
-    child.once("exit", (exitCode, signal) => resolve({ kind: "exit", exitCode, signal }));
-    child.once("error", (cause) => resolve({ kind: "error", cause }));
-  });
-  const pendingHandles = new Set(["leader", "stdin", "stdout", "stderr"]);
-  const released = Promise.all([
-    leader.then(() => pendingHandles.delete("leader")),
-    ...["stdin", "stdout", "stderr"].map((name) => new Promise((resolve) => child[name].once("close", () => {
-      pendingHandles.delete(name);
-      resolve();
-    })))
-  ]);
-  const closed = new Promise((resolve) => {
-    child.once("error", (error) => {
-      spawnFailure = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
-        cause: error
-      });
-      controller.abort(spawnFailure);
-    });
-    child.once("close", (exitCode, signal) => resolve({ exitCode, signal }));
-  });
-  child.stdin.on("error", (error) => {
-    if (!(("code" in error) && error.code === "EPIPE"))
-      controller.abort(error);
-  });
-  const drain = async (stream, channel, captured) => {
-    for await (const chunk of stream) {
-      controller.signal.throwIfAborted();
-      if (!(chunk instanceof Uint8Array))
-        throw new TypeError("Expected binary command output");
-      total += chunk.byteLength;
-      if (options.maxOutputBytes !== undefined && total > options.maxOutputBytes)
-        throw new NativeCommandError2("COMMAND_LIMIT", "Command output budget exceeded");
-      if (options.capture)
-        captured.push(Uint8Array.from(chunk));
-      if (options.onOutput)
-        await raceAbort(Promise.resolve().then(() => {
-          controller.signal.throwIfAborted();
-          return options.onOutput?.(chunk, channel, controller.signal);
-        }), controller.signal);
-    }
-  };
-  const result = (async () => {
-    try {
-      onSpawn?.(child);
-      child.stdin.end(options.stdin);
-      const drains = Promise.all([
-        drain(child.stdout, "stdout", stdout),
-        drain(child.stderr, "stderr", stderr)
-      ]);
-      await raceAbort(Promise.all([drains, leader.then(settle)]), controller.signal);
-      const status = await raceAbort(closed, controller.signal);
-      if (spawnFailure !== undefined)
-        throw spawnFailure;
-      return { ...status, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) };
-    } catch (error) {
-      controller.abort(error);
-      child.stdin.destroy();
-      child.stdout.destroy();
-      child.stderr.destroy();
-      const cleanup = await Promise.allSettled([
-        settle({ kind: "error", cause: error }),
-        stopCommandGroup(child.pid, options.killGraceMs, options.cleanupTimeoutMs).then(async () => {
-          try {
-            await waitForCommandClose(released, options.cleanupTimeoutMs);
-          } catch (cause) {
-            throw new Error(`Command handles remained open: ${[...pendingHandles].join(", ")}`, {
-              cause
-            });
-          }
-        })
-      ]);
-      const failures = cleanup.flatMap((item) => item.status === "rejected" && item.reason !== error ? [item.reason] : []);
-      if (failures.length) {
-        throw commandCleanupError(new AggregateError([error, ...failures], "Command failed and cleanup failed"));
-      }
-      throw error;
-    } finally {
-      finished = true;
-      if (timer !== undefined)
-        clearTimeout(timer);
-      options.signal?.removeEventListener("abort", abort);
-      controller.abort(new Error("Command completed"));
-    }
-  })();
-  result.catch(() => {
-    return;
-  });
-  return {
-    result,
-    async stop() {
-      if (!finished)
-        controller.abort(new DOMException("Command stopped", "AbortError"));
-      await result.then(() => {
-        return;
-      }, () => {
-        return;
-      });
-    }
-  };
-}
-
-export { NativeCommandError2, startNativeCommand };