stitchkit 0.103.10 → 0.103.12

package/dist/process/launch.d.ts

@@ -0,0 +1,74 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { type ParsedNativeCommandOptions } from './contract.js';
+import { type NativeCommandTransport } from './transport.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;
+}
+export 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, onAcquired: (transport: NativeCommandTransport) => void): {
+    stdout: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    stderr: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    start(): void;
+    child: NativeCommandLaunchedProcess;
+    leader: Promise<{
+        kind: "exit";
+        exitCode: number | null;
+        signal: string | null;
+    } | {
+        kind: "error";
+        cause: unknown;
+    }>;
+    closed: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    released: Promise<void>;
+    pendingHandles: Set<string>;
+    stdin: import("node:stream").Writable | undefined;
+    observe(onFailure: (cause: Error) => void): void;
+    capture(): {
+        stdout: NativeCommandLaunchedOutput | Readable;
+        stderr: NativeCommandLaunchedOutput | Readable;
+    };
+    pipeDestructor(name: 'stdout' | 'stderr', destroy: () => unknown): 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,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAsB,KAAK,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAElF,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,MAAM,WAAW,2BAA2B;IAC1C,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;AAwED,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,EACtC,UAAU,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CxD"}

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/owned-child.d.ts

@@ -0,0 +1,10 @@
+/** Only this native spawn can establish group ownership; structural PIDs cannot. */
+export declare function spawnOwnedCommand(input: {
+    executable: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    group: boolean;
+}): import("node:child_process").ChildProcessWithoutNullStreams;
+export declare function ownsCommandGroup(child: object): boolean;
+//# sourceMappingURL=owned-child.d.ts.map

package/dist/process/owned-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-child.d.ts","sourceRoot":"","sources":["../../src/process/owned-child.ts"],"names":[],"mappings":"AAIA,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;CAChB,+DASA;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD"}

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

@@ -0,0 +1,4 @@
+import { NativeCommandError } from './contract.js';
+/** A failed native admission still owns one bounded external-resource settlement. */
+export declare function failedCommandStart(cause: unknown, cleanup: (error: NativeCommandError) => Promise<void>): Promise<never>;
+//# 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,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,qFAAqF;AACrF,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,GACpD,OAAO,CAAC,KAAK,CAAC,CAMhB"}

package/dist/process/transport.d.ts

@@ -0,0 +1,30 @@
+import { Readable, Writable } from 'node:stream';
+import type { NativeCommandLaunchedOutput, NativeCommandLaunchedProcess } from './launch.js';
+/** Acquired before subscriptions: failed setup and normal execution own the same handles. */
+export declare function createCommandTransport(child: NativeCommandLaunchedProcess): {
+    child: NativeCommandLaunchedProcess;
+    leader: Promise<{
+        kind: "exit";
+        exitCode: number | null;
+        signal: string | null;
+    } | {
+        kind: "error";
+        cause: unknown;
+    }>;
+    closed: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    released: Promise<void>;
+    pendingHandles: Set<string>;
+    readonly stdin: Writable | undefined;
+    observe(onFailure: (cause: Error) => void): void;
+    capture(): {
+        stdout: NativeCommandLaunchedOutput | Readable;
+        stderr: NativeCommandLaunchedOutput | Readable;
+    };
+    pipeDestructor(name: 'stdout' | 'stderr', destroy: () => unknown): void;
+    destroy(): void;
+};
+export type NativeCommandTransport = ReturnType<typeof createCommandTransport>;
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/process/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAE1F,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,4BAA4B;;;;;;;;;;;kBAEvB,MAAM,GAAG,IAAI;gBAAU,MAAM,GAAG,IAAI;;;;;uBA6BhE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;;;;;yBAkCpB,QAAQ,GAAG,QAAQ,WAAW,MAAM,OAAO;;EAmBnE;AAED,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/llms/agent-runtime-sandbox.txt

@@ -15,6 +15,12 @@ Also read:
 ---
 title: Optional process sandbox
 description: Linux namespace isolation, durable workspaces and a host credential gateway.
+updated: 2026-10-03 14:47 +07:00
+participants:
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-03 14:47 +07:00
 ---
 
 # Optional process sandbox
@@ -84,7 +90,9 @@ Unsupported backends omit the binding and the factory refuses explicitly.
 Stop also kills coding commands. Both launch paths share the configured
 `maxConcurrentCommands` admission limit (default 8); an occupied slot gives
 `SANDBOX_BUSY` before another process starts. This counts direct commands, not
-guest descendants. Required restrictions are checked again during preparation;
+guest descendants. A direct launch retains its slot through terminal group cleanup,
+including descendants that outlive the leader. Required restrictions are checked again
+during preparation;
 a network-policy change invalidates an outstanding prepared launch. After
 reconnect, create the coding profile from the new handle; old tools remain stopped.
 

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-03 13:36 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -25,6 +25,10 @@ participants:
     harness: Codex
     model: GPT-6
     at: 2026-10-02 00:08 +07:00
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-03 13:36 +07:00
 ---
 
 # Native IO
@@ -131,6 +135,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 +194,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,14 +218,23 @@ 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
 proven-dead owner's file. Set `ownerlessGraceMs: null` to refuse every age-only reclaim,
 including ownerless reclaim guards. The default remains 5000 ms for existing clients.
-Восстановление stale reclaim guard использует тот же lock owner и следующий guard:
-проверка inode и удаление выполняются под ним. Конкурирующий writer не обходит guard,
-пока прежнее удаление приостановлено; live и unknown lifetime evidence остаются отказом.
+Stale reclaim guards use the same lock owner and a child guard for the inode check and
+unlink. Recovery depth is capped at 16; a deeper stale chain refuses recovery with a depth diagnosis retained as the cause of
+the bounded `LOCK_TIMEOUT`. Live owners, unknown process-lifetime evidence and unsafe records are never
+reclaimed. Concurrent writers cannot bypass a guard while a prior unlink is paused.
 
 ## Libraries with a Zod-only runtime
 
@@ -221,6 +264,26 @@ Stitchkit leaf fails there. A separate schema-only entry must not import the nat
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.
 
+## Qualification boundaries
+
+Native command cleanup owns the child before launch subscriptions are installed. Setup
+refusal still settles leader closure and teardown within the cleanup budget; failure to
+prove closure reports `COMMAND_CLEANUP` with the original failure retained. Process-group
+signaling requires evidence from the actual detached launcher, not a structural PID field.
+The built-in sandbox transport carries that ownership across the package's split entrypoints.
+Internal finite deadlines and Darwin retry admission use monotonic elapsed time.
+
+Linux UID-refusal qualification is a separate privileged installed-package proof in Bun
+and real Node; an unsupported platform or insufficient UID reports an explicit skip.
+A generic native-owner marker does not certify the privileged case. Real Darwin CI remains
+the qualification for native Darwin behavior.
+
+Local filesystem tests do not attest delayed NFS visibility, shared-volume microVM or gVisor
+ownership, actual PGID reuse, power-loss durability or macOS full-sync behavior. Those
+require their actual topology or failure environment. The default ownerless grace remains
+5000 ms; stricter callers can retain `ownerlessGraceMs: null`. No age-only observation
+proves a partially published owner's process dead.
+
 ==============================================================================
 # API reference: `stitchkit/process`  (docs/api/reference.md)
 ==============================================================================
@@ -234,9 +297,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;
@@ -7894,6 +7900,12 @@ boundary is required. Send and projection callbacks own their external deadlines
 ---
 title: Optional process sandbox
 description: Linux namespace isolation, durable workspaces and a host credential gateway.
+updated: 2026-10-03 14:47 +07:00
+participants:
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-03 14:47 +07:00
 ---
 
 # Optional process sandbox
@@ -7963,7 +7975,9 @@ Unsupported backends omit the binding and the factory refuses explicitly.
 Stop also kills coding commands. Both launch paths share the configured
 `maxConcurrentCommands` admission limit (default 8); an occupied slot gives
 `SANDBOX_BUSY` before another process starts. This counts direct commands, not
-guest descendants. Required restrictions are checked again during preparation;
+guest descendants. A direct launch retains its slot through terminal group cleanup,
+including descendants that outlive the leader. Required restrictions are checked again
+during preparation;
 a network-policy change invalidates an outstanding prepared launch. After
 reconnect, create the coding profile from the new handle; old tools remain stopped.
 
@@ -8031,7 +8045,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-03 13:36 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -8041,6 +8055,10 @@ participants:
     harness: Codex
     model: GPT-6
     at: 2026-10-02 00:08 +07:00
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-03 13:36 +07:00
 ---
 
 # Native IO
@@ -8147,6 +8165,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 +8224,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,14 +8248,23 @@ 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
 proven-dead owner's file. Set `ownerlessGraceMs: null` to refuse every age-only reclaim,
 including ownerless reclaim guards. The default remains 5000 ms for existing clients.
-Восстановление stale reclaim guard использует тот же lock owner и следующий guard:
-проверка inode и удаление выполняются под ним. Конкурирующий writer не обходит guard,
-пока прежнее удаление приостановлено; live и unknown lifetime evidence остаются отказом.
+Stale reclaim guards use the same lock owner and a child guard for the inode check and
+unlink. Recovery depth is capped at 16; a deeper stale chain refuses recovery with a depth diagnosis retained as the cause of
+the bounded `LOCK_TIMEOUT`. Live owners, unknown process-lifetime evidence and unsafe records are never
+reclaimed. Concurrent writers cannot bypass a guard while a prior unlink is paused.
 
 ## Libraries with a Zod-only runtime
 
@@ -8237,6 +8294,26 @@ Stitchkit leaf fails there. A separate schema-only entry must not import the nat
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.
 
+## Qualification boundaries
+
+Native command cleanup owns the child before launch subscriptions are installed. Setup
+refusal still settles leader closure and teardown within the cleanup budget; failure to
+prove closure reports `COMMAND_CLEANUP` with the original failure retained. Process-group
+signaling requires evidence from the actual detached launcher, not a structural PID field.
+The built-in sandbox transport carries that ownership across the package's split entrypoints.
+Internal finite deadlines and Darwin retry admission use monotonic elapsed time.
+
+Linux UID-refusal qualification is a separate privileged installed-package proof in Bun
+and real Node; an unsupported platform or insufficient UID reports an explicit skip.
+A generic native-owner marker does not certify the privileged case. Real Darwin CI remains
+the qualification for native Darwin behavior.
+
+Local filesystem tests do not attest delayed NFS visibility, shared-volume microVM or gVisor
+ownership, actual PGID reuse, power-loss durability or macOS full-sync behavior. Those
+require their actual topology or failure environment. The default ownerless grace remains
+5000 ms; stricter callers can retain `ownerlessGraceMs: null`. No age-only observation
+proves a partially published owner's process dead.
+
 
 ==============================================================================
 # Guide: Generic application primitives  (docs/guide/primitives.md)
@@ -21191,9 +21268,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
@@ -38,7 +38,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.8 KB
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
-- **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
+- **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.3 KB
 - **stitchkit/files**: [llms/files.txt](llms/files.txt) 4.5 KB
 - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 26.9 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 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) 20.0 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.12",
   "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",