stitchkit 0.108.1 → 0.108.3

package/llms-full.txt

@@ -61,7 +61,8 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
-| `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
+| `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture, process-group cancellation and opt-in Linux/Darwin owner-loss cleanup |
+| `stitchkit/process/owner-loss` | bundled server entry (Bun, POSIX) | evolving | narrow bootstrap that keeps the process runner lazy while carrying its owner-loss guard in a single-file bundle |
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
@@ -8322,6 +8323,7 @@ console.log(captured.exitCode, new TextDecoder().decode(captured.stdout))
 const lifetime = new AbortController()
 await runNativeCommand({
   executable: '/usr/bin/git', args: ['status'], signal: lifetime.signal,
+  ownerLoss: 'terminate', // also stop its group if this JavaScript process is SIGKILLed
   onOutput: async (bytes, channel, outputSignal) => {
     outputSignal.throwIfAborted()
     await output.write(bytes, channel, outputSignal) // application-owned bounded sink
@@ -8384,6 +8386,35 @@ sink cause is kept; a cleanup failure is a `NativeCommandError` with `COMMAND_CL
 refuses with `COMMAND_UNAVAILABLE`; a descendant that has left the group on its own with `setsid` is
 outside this capability. This is one-shot execution, not a PTY, a supervisor or a daemon host.
 
+`ownerLoss: 'terminate'` binds the command group to this JavaScript process even when it cannot run
+cleanup. A package-owned guard becomes the process-group leader, starts the requested executable in
+that group and holds one end of a private inherited kernel channel. The caller holds the other end.
+`SIGKILL`, a crash or any abrupt caller exit closes that end; EOF makes the guard KILL its own group.
+There is no liveness polling and no later PID lookup. Because the guard is still the group leader
+when it signals, its PGID cannot have been reused by a neighbour. The option is available on Linux
+and Darwin under Bun and Node, requires `group: 'own'`, and other platforms refuse it with
+`COMMAND_UNAVAILABLE`. It adds one short-lived process and one descriptor per guarded command, so it
+is opt-in. `onLeaderStarted({ pid })` reports the guard/group leader with this option; output, stdin,
+exit status, deadlines, cancellation and `onLeaderSettled` retain the requested command's behaviour.
+
+An unbundled application already launches the package's own guard module. A single-file bundle
+whose application entry also owns argv routing must load the narrow bootstrap before its dispatcher
+and skip dispatch when it claims the private guard invocation. This is especially relevant when the
+full command runner stays behind a dynamic import:
+
+```ts
+import { bootstrapNativeCommandOwnerLoss } from 'stitchkit/process/owner-loss'
+
+if (!bootstrapNativeCommandOwnerLoss()) {
+  await dispatch(process.argv.slice(2)) // may lazy-import `stitchkit/process`
+}
+```
+
+The bootstrap carries the package-owned guard into the bundle. It returns `false` for application
+argv and `true` only for the private child started by `runNativeCommand`, so the application does
+not read a guard flag or filename. The built file is self-contained; no installed `node_modules`
+is needed beside it.
+
 ### Stopping a command: the `stop` policy
 
 A caller abort, the `timeoutMs` deadline, an exceeded output budget and a failing sink all stop the
@@ -8418,13 +8449,13 @@ dropped, never passed to `onOutput` and never captured, so a leader that writes
 does not meet a broken pipe. The result rejects with the abort reason once the group is gone and the
 pipes are closed, so it can take `graceMs` plus `cleanupTimeoutMs` after the abort.
 
-The grace is a timer inside the process that runs the command. If that process exits first, the
-timer is gone and the group, which is detached into its own session, keeps running: nothing in this
-package can bound it from outside. Abort `killOn` in your shutdown path, so the group is killed
-before the process exits, and let the supervisor own the case where the process dies without a
-shutdown. Under systemd, keep `KillMode=control-group` (the default) so the stop of the unit
-reaches every process in its cgroup, whatever its process group; launchd only kills the job's own
-process group, which a command's group is not.
+The grace is a timer inside the process that runs the command. Without `ownerLoss`, if that process
+exits first, the timer is gone and the group, which is detached into its own session, keeps running.
+Abort `killOn` in your shutdown path so a deliberate shutdown kills the group before exit. For an
+abrupt-exit guarantee, choose `ownerLoss: 'terminate'`; for all groups in a service, let the service
+supervisor own the wider boundary. Under systemd, keep `KillMode=control-group` (the default) so the
+stop of the unit reaches every process in its cgroup, whatever its process group; launchd only kills
+the job's own process group, which an unguarded detached command's group is not.
 
 ### Stopping a group and its descendants
 
@@ -8485,7 +8516,7 @@ becomes `runNativeCommand`; shell policy, command admission, logging, redaction,
 decoder and the operator sink stay with the application. Long signal-only commands stay streaming;
 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
+A child the caller holds until it exits is the same call. A host 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), and the leader's exit code and signal in `onLeaderSettled`: `'exit'`
@@ -8495,7 +8526,9 @@ long the output pipes may stay open after the leader exited: a holder that left
 `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
+`target: 'group'`. Add `ownerLoss: 'terminate'` when the worker must also die after an abrupt host
+loss; in that mode `onLeaderStarted` reports the package guard that leads the same 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.
 
@@ -8529,6 +8562,7 @@ its own, so:
   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`;
+- `ownerLoss` is refused: an owner-loss guard must lead a group that belongs only to the command;
 - 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
@@ -9607,11 +9641,19 @@ string, the schema says what it should be:
 | `z.string()`         | `--name "box"` or a positional                 |
 | `z.number()`         | `--count 3` → `3`                              |
 | `z.boolean()`        | `--active` (presence) / `--active false` / `--no-active` |
+| `z.literal(1)` / `z.literal([1, 2])` | `--level 1` → `1`              |
+| `z.literal(true)`    | `--enabled` / `--no-enabled`                    |
+| `z.literal('007')`   | `--code 007` → `"007"`                          |
 | `z.enum([...])`      | `--size large`                                 |
 | `z.array(z.string())`| `--tag a --tag b` → `["a","b"]`                |
 | `z.object({...})`    | `--opts '{"k":"v"}'` (JSON) or `--opts.k v`    |
 | `.optional()` / `.default()` | not required                           |
 
+Primitive literals use the same coercion through optional, nullable and default wrappers and as
+array elements. A literal set whose members have different primitive types stays lexical because
+argv has no type tag: for `z.literal([7, '007'])`, `--value 007` remains the string `"007"` rather
+than being guessed as the number `7`. The unchanged Zod schema makes the final admission decision.
+
 After a bare boolean flag, the next token is its value when it is exactly
 `true` or `false` — `--active false` turns it off, as it reads. Any other word
 there stays a positional, and `--` makes a literal `false` one too. The same
@@ -23044,7 +23086,7 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `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 |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
 | `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
@@ -23054,6 +23096,14 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `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 |
 
+## `stitchkit/process/owner-loss`
+
+Narrow startup entry for single-file applications that lazy-import `stitchkit/process`.
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `bootstrapNativeCommandOwnerLoss` | function | call before application argv routing; returns `true` only when the package guard owns this invocation, so the application skips its dispatcher while preserving a lazy import of the full command runner |
+
 ## `stitchkit/files/packaging`
 
 `stitchkit/files/packaging` owns `createNativePackaging` and the types

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 46.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 46.7 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
@@ -18,7 +18,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.7 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 47.0 KB → [llms/cli.2.txt](llms/cli.2.txt) 15.4 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 42.8 KB → [llms/cli.2.txt](llms/cli.2.txt) 20.1 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
@@ -56,7 +56,8 @@ 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) 43.3 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 45.8 KB
+- **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 
 ## Upgrading slices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.108.1",
+  "version": "0.108.3",
   "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",
@@ -249,6 +249,10 @@
       "types": "./dist/entrypoints/process.d.ts",
       "import": "./dist/entrypoints/process.js"
     },
+    "./process/owner-loss": {
+      "types": "./dist/entrypoints/process/owner-loss.d.ts",
+      "import": "./dist/entrypoints/process/owner-loss.js"
+    },
     "./files/packaging": {
       "types": "./dist/entrypoints/files/packaging.d.ts",
       "import": "./dist/entrypoints/files/packaging.js"