stitchkit 0.105.2 → 0.106.1

package/llms/{upgrading-0.68.0-0.94.0.txt → upgrading-0.69.0-0.95.0.txt}

@@ -1,14 +1,56 @@
-# Upgrading 0.68.0 → 0.94.0 — stitchkit docs slice
+# Upgrading 0.69.0 → 0.95.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.95.0
+
+One breaking change in `stitchkit/application`: the process lifecycle ledger
+counts downtime as the window nobody answered in, and gains the `draining`
+phase and the `startup-failed` outcome. A ledger file written by an earlier
+version loads unchanged — the new `unavailableAt` reads as `null`.
+
+1. **Read downtime from the ready fact.** **Who must act:** a project that
+   reads `downtimeMs` from a `started` fact. It is gone from `StartFact`; the
+   number it carried is `processGapMs`. The downtime now arrives with the new
+   run's readiness:
+
+   ```ts
+   // before
+   ledger.subscribe((fact) => {
+     if (fact.type === 'started') report(fact.previousExit, fact.downtimeMs);
+   });
+   // after
+   ledger.subscribe((fact) => {
+     if (fact.type === 'started') previousExit = fact.previousExit;
+     if (fact.type === 'ready') report(previousExit, fact.downtimeMs);
+   });
+   ```
+
+2. **Handle the new values.** **Who must act:** a project that switches
+   exhaustively over `LifecycleTermination` (new: `draining`,
+   `startup-failed`), `PreviousExit` (new: `startup-failed`) or
+   `ProcessLifecycleFact` (new: `DrainingFact`, `type: 'draining'`). The type
+   checker names each switch. An open run is `active` or `draining`; a check
+   written as `termination === 'active'` to mean "still running" becomes
+   `termination === 'active' || termination === 'draining'`.
+   `TransitionReadyInput` is renamed `TransitionRunInput` — the same fields,
+   now also taken by `transitionProcessDraining`; rename the import.
+
+3. **Record the drain and the readiness when driving the ledger by hand.**
+   **Who must act:** only a project that calls `createProcessLifecycleLedger`
+   methods itself instead of mounting `lifecycleLedgerResource`. Call
+   `recordDraining()` where the application stops admitting work, before it
+   drains; without it downtime is counted from the recorded stop. Call
+   `recordReady()` when the run serves; a run stopped without it now ends
+   `startup-failed`, not `clean`.
+
 ## Released migration: 0.94.0
 
 One breaking minor that consolidates: tool options move into one group, and
@@ -1107,53 +1149,3 @@ else renderExistingRole(message)
 
 No data migration is needed. The schema still accepts all earlier records, and applications that
 do not exhaustively branch over these unions compile unchanged.
-
-## Released migration: 0.68.0
-
-### Make Unix transport selection explicit outside Bun
-
-The legacy `unix` option remains a Bun convenience, but on Node or another
-runtime it now fails before dispatch. Replace it with the owned adapter and close
-that adapter with the application:
-
-```ts
-// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
-const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
-
-// after — Bun and Node; every dispatch and redirect stays on the socket
-import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
-const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
-const http = createHttpClient({ baseUrl, fetch: transport.fetch })
-// during shutdown
-await transport.close()
-```
-
-Do not automatically replay `possibly-dispatched`: a timeout or connection loss
-after bytes left the process does not prove that a write did not happen.
-
-### Choose tolerant stream parsing explicitly
-
-`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
-over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
-bad records, retain that policy explicitly:
-
-```ts
-// before — malformed input disappeared implicitly
-parseNDJSON(response)
-
-// after — ordinary fail-closed path
-parseNDJSON(response, { maxLineBytes: 256 * 1024 })
-
-// after — deliberately tolerant path
-parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
-```
-
-### Extend exhaustive framework-error handling
-
-If a switch makes `StitchErrorCode` exhaustive, add
-`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
-`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
-status map needs no change (ADR 0105).
-
-The admission/channel APIs and endpoint `stream` descriptor are additive; raw
-responses and raw `streamingRoute` remain supported.

package/llms/{upgrading-0.95.0-0.105.0.txt → upgrading-0.96.0-0.106.0.txt}

@@ -1,14 +1,51 @@
-# Upgrading 0.95.0 → 0.105.0 — stitchkit docs slice
+# Upgrading 0.96.0 → 0.106.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.95.0 → 0.105.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.96.0 → 0.106.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.95.0 → 0.105.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.96.0 → 0.106.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.106.0
+
+### a stopped leader settles as stopped
+
+**Who must act:** code passed to `onLeaderSettled` of `runNativeCommand` (`stitchkit/process`) that
+reads `kind: 'error'` as "the command was stopped". Code that only handles `kind: 'exit'`, or does
+not pass `onLeaderSettled`, needs no change.
+
+A command stopped by a caller abort, its `timeoutMs`, an exceeded output budget or a failing sink
+used to settle at once as `{ kind: 'error', cause }`. It now waits for the stop signals and settles
+as `{ kind: 'stopped', cause, exitCode, signal }`, with how the kernel reported the leader's end
+([ADR 0248](../decisions/0248-a-stopped-leader-settles-with-its-exit-and-a-command-may-join-the-callers-group.md)).
+`'error'` is left for a leader whose exit was never observed.
+
+1. Where the hook handled a stop under `'error'`, handle `'stopped'` there, and take the exit from
+   the event instead of reading the child process:
+
+   ```ts
+   // before
+   onLeaderSettled: (event) => {
+     if (event.kind === 'exit') record(event.exitCode, event.signal)
+     else stopped(event.cause)
+   }
+   // after
+   onLeaderSettled: (event) => {
+     if (event.kind === 'error') return failed(event.cause)
+     record(event.exitCode, event.signal)
+     if (event.kind === 'stopped') stopped(event.cause)
+   }
+   ```
+
+   Search pattern: `onLeaderSettled` together with `kind === 'error'` or `kind !== 'exit'`.
+2. Type-check: an exhaustive `switch (event.kind)` without a `'stopped'` case fails on the new kind.
+3. A hook that stops an external scope on a stopped command now runs once the leader is gone,
+   still bounded by `cleanupTimeoutMs`; no change is needed unless the leader waited for that scope
+   to exit (it gets KILL when the grace ends either way).
+
 ## Released migration: 0.105.0
 
 ### CLI publication has its own entrypoint
@@ -895,45 +932,3 @@ it; only a context built by hand needs it.
    hand before `bot.stop()`. A project that wrote its own `getUpdates`
    transformer for this (waiting on `app.admission` before returning a batch)
    deletes it; keeping both waits twice and is harmless.
-
-## Released migration: 0.95.0
-
-One breaking change in `stitchkit/application`: the process lifecycle ledger
-counts downtime as the window nobody answered in, and gains the `draining`
-phase and the `startup-failed` outcome. A ledger file written by an earlier
-version loads unchanged — the new `unavailableAt` reads as `null`.
-
-1. **Read downtime from the ready fact.** **Who must act:** a project that
-   reads `downtimeMs` from a `started` fact. It is gone from `StartFact`; the
-   number it carried is `processGapMs`. The downtime now arrives with the new
-   run's readiness:
-
-   ```ts
-   // before
-   ledger.subscribe((fact) => {
-     if (fact.type === 'started') report(fact.previousExit, fact.downtimeMs);
-   });
-   // after
-   ledger.subscribe((fact) => {
-     if (fact.type === 'started') previousExit = fact.previousExit;
-     if (fact.type === 'ready') report(previousExit, fact.downtimeMs);
-   });
-   ```
-
-2. **Handle the new values.** **Who must act:** a project that switches
-   exhaustively over `LifecycleTermination` (new: `draining`,
-   `startup-failed`), `PreviousExit` (new: `startup-failed`) or
-   `ProcessLifecycleFact` (new: `DrainingFact`, `type: 'draining'`). The type
-   checker names each switch. An open run is `active` or `draining`; a check
-   written as `termination === 'active'` to mean "still running" becomes
-   `termination === 'active' || termination === 'draining'`.
-   `TransitionReadyInput` is renamed `TransitionRunInput` — the same fields,
-   now also taken by `transitionProcessDraining`; rename the import.
-
-3. **Record the drain and the readiness when driving the ledger by hand.**
-   **Who must act:** only a project that calls `createProcessLifecycleLedger`
-   methods itself instead of mounting `lifecycleLedgerResource`. Call
-   `recordDraining()` where the application stops admitting work, before it
-   drains; without it downtime is counted from the recorded stop. Call
-   `recordReady()` when the run serves; a run stopped without it now ends
-   `startup-failed`, not `clean`.

package/llms/upgrading.txt

@@ -11,10 +11,10 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.95.0 → 0.105.0: `llms/upgrading-0.95.0-0.105.0.txt`
-- 0.68.0 → 0.94.0: `llms/upgrading-0.68.0-0.94.0.txt`
-- 0.53.0 → 0.67.0: `llms/upgrading-0.53.0-0.67.0.txt`
-- 0.37.0 → 0.50.0: `llms/upgrading-0.37.0-0.50.0.txt`
+- 0.96.0 → 0.106.0: `llms/upgrading-0.96.0-0.106.0.txt`
+- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
+- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
+- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
 
 # Upgrading stitchkit
 

package/llms-full.txt

@@ -74,12 +74,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 50 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 51 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 50 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 51 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +91,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 50 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 51 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -8355,7 +8355,9 @@ command the same way, by its `stop` policy:
 | `graceMs` | How long the leader (or the group) has to leave before the whole group gets KILL. 0 to 3 600 000 (one hour). Required. |
 | `killOn` | Optional `AbortSignal`. Its abort stops the command with KILL to the whole group at once, also in the middle of a grace. |
 
-Omitting `stop` means `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }`.
+Omitting `stop` means `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }`; a command in the
+caller's group (`group: 'caller'`) stops its leader alone, so its default is `target: 'leader'`
+and a group target is refused (see [Terminal commands](#terminal-commands-inherited-stdio-and-the-callers-group)).
 
 ```ts
 // Cooperative cancellation: the leader rolls its work back, its helpers are not asked.
@@ -8410,13 +8412,15 @@ so a helper started in the background races the leader:
 
 | launched by the leader as | after the leader exits |
 |---|---|
-| `setsid -f helper` (returns once the new session exists) | survives |
+| `setsid -f helper` | usually survives: `setsid -f` forks and returns at once, and the child calls `setsid()` a moment later, so a leader that exits immediately can still catch it in the group (13 of 300 launches under CPU load) |
 | `setsid helper &`, `(setsid helper &)`, `nohup helper &` | stopped: the leader usually exits before the background job has left the group |
+| a launch the leader waits on until the helper reports it has left the group | survives |
 | any of these under `descendants: 'leave'` | survives |
 
-Start a daemon so that the session exists before the leader returns (`setsid -f`, or the
-daemon's own double fork followed by the leader waiting for it), or declare `'leave'`. Declare
-`'leave'` only for a helper that has to outlive the command while staying in its group:
+Start a daemon so that the leader waits for the session to exist before it returns: the helper
+writes its pid, or prints a line, only after its own `setsid()`, and the leader waits for that.
+Or declare `'leave'`. Declare `'leave'` only for a helper that has to outlive the command while
+staying in its group:
 
 ```ts
 await runNativeCommand({
@@ -8426,7 +8430,8 @@ await runNativeCommand({
 })
 ```
 
-A command whose group this package did not create (a structural
+A command in the caller's group (`group: 'caller'`) has no group of its own: `descendants` is
+refused there and nothing is stopped after its leader exits. A command whose group this package did not create (a structural
 launcher supplied by a host) has no group to stop, and `descendants` has nothing to act on there.
 
 
@@ -8442,26 +8447,68 @@ bounded tar or capture commands get their own explicit limits.
 A child the caller holds until it exits is the same call. A guardian that forwards its own SIGTERM
 passes an abort signal and `stop: { target: 'leader', signal: 'SIGTERM', graceMs }`. It records the
 pid in `onLeaderStarted({ pid })`, which runs once right after the leader exists (a throw stops the
-command with that error), reads the exit code and signal in `onLeaderSettled` before the pipes
-drain, and reads stderr through `onOutput` or `capture` with `maxOutputBytes`. `drainTimeoutMs`
-bounds how long the output pipes may stay open after the leader exited: a holder that left the
-group with `setsid` keeps them open, and without the option the command waits for it until
-`timeoutMs` or the signal; with it the command ends with `COMMAND_CLEANUP` (a holder inside the
-group is already stopped by `descendants`). A worker whose whole group must stop on abort is the
-default `target: 'group'`. A child that inherits the caller's terminal is outside this
-capability: every command runs in a group of its own, and a background group that reads the
-terminal is stopped by the kernel (`SIGTTIN`), so an interactive re-execution stays a plain
-spawn in the caller's group. Importing one leaf does not make
+command with that error), and the leader's exit code and signal in `onLeaderSettled`: `'exit'`
+when the leader ended on its own, `'stopped'` with the same fields when the guardian stopped it.
+It reads stderr through `onOutput` or `capture` with `maxOutputBytes`. `drainTimeoutMs` bounds how
+long the output pipes may stay open after the leader exited: a holder that left the group with
+`setsid` keeps them open, and without the option the command waits for it until `timeoutMs` or
+the signal; with it the command ends with `COMMAND_CLEANUP` (a holder inside the group is already
+stopped by `descendants`). A worker whose whole group must stop on abort is the default
+`target: 'group'`. A command that uses the caller's terminal is the next section. Importing one leaf does not make
 installing the whole npm package smaller; choose a dependency after measuring packed size and its
 dependency closure.
 
+## Terminal commands: inherited stdio and the caller's group
+
+An operator CLI that re-runs itself, or any command that prompts or prints in colour, needs the
+caller's terminal itself rather than pipes. Two options give it that:
+
+```ts
+const { exitCode } = await runNativeCommand({
+  executable: process.execPath, args: [cliPath, ...argv], envPolicy: 'ambient',
+  signal: shutdown.signal,
+  stdio: 'inherit',   // the command's stdin, stdout and stderr are the caller's: a TTY stays a TTY
+  group: 'caller',    // it joins the caller's process group, so a Ctrl-C at the terminal reaches it
+})
+process.exitCode = exitCode ?? 1
+```
+
+`stdio: 'inherit'` hands the caller's three descriptors to the command; its bytes never pass
+through this package, so `capture`, `onOutput`, `stdin`, `maxOutputBytes` and `drainTimeoutMs` are
+refused by name with it, and the result's buffers stay empty.
+
+`group: 'caller'` keeps the command in the caller's process group instead of a group of its own.
+That is what an interactive command needs: the terminal sends Ctrl-C to its foreground group,
+and a command in a group of its own is a background group there, which the kernel stops
+(`SIGTTIN`) as soon as it reads the terminal. In the caller's group the command has no group of
+its own, so:
+
+- a stop signals the leader alone: `stop.target` is `'leader'` (the default here is
+  `{ target: 'leader', signal: 'SIGTERM', graceMs: 100 }`), and `target: 'group'` is refused,
+  because a group signal would reach the caller;
+- `descendants` does not apply and is refused: what the leader leaves behind belongs to the
+  caller's group, and `descendantsStopped` is always `false`;
+- a Ctrl-C reaches the caller too; handle `SIGINT` in the caller when it must outlive the command.
+
+The two options are independent: `stdio: 'inherit'` alone keeps colour and `isatty` for a command
+that never reads the terminal, and `group: 'caller'` alone forwards Ctrl-C to a piped command.
+
 ## Resource-scoped launchers and shared owners
 
 `onLeaderSettled(event, signal)` observes leader exit before inherited stdout/stderr pipes
 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. Synchronous native launch
+The callback runs once, with one of three events:
+
+| `event.kind` | when | carries |
+|---|---|---|
+| `'exit'` | the leader ended on its own | `exitCode`, `signal` as the kernel reported them |
+| `'stopped'` | the command was stopped (caller abort, `timeoutMs`, output budget, failing sink) and the leader's exit after the stop signals was observed | the stop's `cause`, and the leader's `exitCode` and `signal` (for example `SIGTERM`, or `SIGKILL` once the grace ended) |
+| `'error'` | no exit of the leader was observed: it could not start, or its exit did not arrive within `cleanupTimeoutMs` | the `cause` |
+
+A leader that ended on its own settles before the pipes drain; a stopped one settles after the
+stop sequence, once its exit is known. A stop that comes after the leader already exited (a
+deadline while a helper holds the pipe) does not change its `'exit'` event. Unavailable
+executables, output sink 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.
@@ -15533,6 +15580,43 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.106.0
+
+### a stopped leader settles as stopped
+
+**Who must act:** code passed to `onLeaderSettled` of `runNativeCommand` (`stitchkit/process`) that
+reads `kind: 'error'` as "the command was stopped". Code that only handles `kind: 'exit'`, or does
+not pass `onLeaderSettled`, needs no change.
+
+A command stopped by a caller abort, its `timeoutMs`, an exceeded output budget or a failing sink
+used to settle at once as `{ kind: 'error', cause }`. It now waits for the stop signals and settles
+as `{ kind: 'stopped', cause, exitCode, signal }`, with how the kernel reported the leader's end
+([ADR 0248](../decisions/0248-a-stopped-leader-settles-with-its-exit-and-a-command-may-join-the-callers-group.md)).
+`'error'` is left for a leader whose exit was never observed.
+
+1. Where the hook handled a stop under `'error'`, handle `'stopped'` there, and take the exit from
+   the event instead of reading the child process:
+
+   ```ts
+   // before
+   onLeaderSettled: (event) => {
+     if (event.kind === 'exit') record(event.exitCode, event.signal)
+     else stopped(event.cause)
+   }
+   // after
+   onLeaderSettled: (event) => {
+     if (event.kind === 'error') return failed(event.cause)
+     record(event.exitCode, event.signal)
+     if (event.kind === 'stopped') stopped(event.cause)
+   }
+   ```
+
+   Search pattern: `onLeaderSettled` together with `kind === 'error'` or `kind !== 'exit'`.
+2. Type-check: an exhaustive `switch (event.kind)` without a `'stopped'` case fails on the new kind.
+3. A hook that stops an external scope on a stopped command now runs once the leader is gone,
+   still bounded by `cleanupTimeoutMs`; no change is needed unless the leader waited for that scope
+   to exit (it gets KILL when the grace ends either way).
+
 ## Released migration: 0.105.0
 
 ### CLI publication has its own entrypoint
@@ -22646,12 +22730,12 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `onLeaderStarted({ pid })` (once, after the leader exists), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
+| `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` and a group stop); `onLeaderStarted({ pid })` (once, after the leader exists), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
-| `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
+| `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 | 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 |
+| `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.txt

@@ -56,15 +56,15 @@ 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) 36.2 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 39.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 2.8 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.95.0 → 0.105.0**: [llms/upgrading-0.95.0-0.105.0.txt](llms/upgrading-0.95.0-0.105.0.txt) 46.8 KB
-- **Upgrading 0.68.0 → 0.94.0**: [llms/upgrading-0.68.0-0.94.0.txt](llms/upgrading-0.68.0-0.94.0.txt) 46.5 KB
-- **Upgrading 0.53.0 → 0.67.0**: [llms/upgrading-0.53.0-0.67.0.txt](llms/upgrading-0.53.0-0.67.0.txt) 46.1 KB
-- **Upgrading 0.37.0 → 0.50.0**: [llms/upgrading-0.37.0-0.50.0.txt](llms/upgrading-0.37.0-0.50.0.txt) 31.6 KB
+- **Upgrading 0.96.0 → 0.106.0**: [llms/upgrading-0.96.0-0.106.0.txt](llms/upgrading-0.96.0-0.106.0.txt) 46.6 KB
+- **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
+- **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
+- **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.105.2",
+  "version": "0.106.1",
   "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",
@@ -265,10 +265,10 @@
     "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": "bun ../../scripts/sync-package-readme.ts && bun ../../scripts/gen-llms.ts && bun run build",
-    "test": "bun test",
+    "test": "bun ../../scripts/test-leak-gate.ts -- bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
     "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
-    "consumer-lane": "bun scripts/consumer-lane/run.mjs",
+    "consumer-lane": "bun ../../scripts/test-leak-gate.ts -- bun scripts/consumer-lane/run.mjs",
     "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts",
     "bench:durable-store": "bun scripts/bench-durable-store.ts",
     "build:entrypoints": "bun scripts/generate-native-assets.ts && bun scripts/build-entrypoints.mjs"