stitchkit 0.105.2 → 0.106.1

package/dist/process/contract.d.ts

@@ -3,13 +3,21 @@ declare const NativeCommandSettlementSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     kind: z.ZodLiteral<"exit">;
     exitCode: z.ZodNullable<z.ZodNumber>;
     signal: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"stopped">;
+    cause: z.ZodUnknown;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    signal: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"error">;
     cause: z.ZodUnknown;
 }, z.core.$strip>], "kind">;
 /**
- * How a command's main process ended: `exit` with code and signal, or `error` with the cause;
- * `onLeaderSettled` receives it before inherited pipes finish draining.
+ * How a command's main process ended: `exit` with code and signal when it ended on its own;
+ * `stopped` when the command was stopped (abort, deadline, output budget, failing sink) and the
+ * kernel then reported how the leader ended, with the stop's `cause`; `error` when no exit of the
+ * leader was observed (it could not start, or its exit never arrived). A leader that ends on its
+ * own settles before inherited pipes finish draining, a stopped one after the stop signals.
  */
 export type NativeCommandSettlement = z.infer<typeof NativeCommandSettlementSchema>;
 /**
@@ -37,11 +45,12 @@ declare const NativeCommandStopPolicySchema: z.ZodObject<{
 /**
  * How a cancelled command is stopped: `signal` goes to the whole group (`target: 'group'`) or
  * only to the leader (`'leader'`), the group gets KILL once the grace ends (for `'leader'`, as
- * soon as the leader has exited), and an abort of `killOn` stops at once with KILL.
+ * soon as the leader has exited), and an abort of `killOn` stops at once with KILL. A command in
+ * the caller's group (`group: 'caller'`) takes `'leader'` only, and KILL reaches its leader alone.
  */
 export type NativeCommandStopPolicy = z.input<typeof NativeCommandStopPolicySchema>;
 export type ParsedNativeCommandStopPolicy = z.output<typeof NativeCommandStopPolicySchema>;
-export declare const NativeCommandOptionsSchema: z.ZodObject<{
+export declare const NativeCommandOptionsSchema: z.ZodPipe<z.ZodObject<{
     executable: z.ZodString;
     args: z.ZodDefault<z.ZodArray<z.ZodString>>;
     cwd: z.ZodOptional<z.ZodString>;
@@ -64,7 +73,15 @@ export declare const NativeCommandOptionsSchema: z.ZodObject<{
         pid: number;
     }) => void>>;
     drainTimeoutMs: z.ZodOptional<z.ZodNumber>;
-    stop: z.ZodDefault<z.ZodObject<{
+    group: z.ZodDefault<z.ZodEnum<{
+        caller: "caller";
+        own: "own";
+    }>>;
+    stdio: z.ZodDefault<z.ZodEnum<{
+        inherit: "inherit";
+        pipe: "pipe";
+    }>>;
+    stop: z.ZodOptional<z.ZodObject<{
         target: z.ZodEnum<{
             group: "group";
             leader: "leader";
@@ -80,12 +97,68 @@ export declare const NativeCommandOptionsSchema: z.ZodObject<{
         graceMs: z.ZodNumber;
         killOn: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
     }, z.core.$strict>>;
-    descendants: z.ZodDefault<z.ZodEnum<{
+    descendants: z.ZodOptional<z.ZodEnum<{
         leave: "leave";
         "terminate-after-leader": "terminate-after-leader";
     }>>;
     cleanupTimeoutMs: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strict>;
+}, z.core.$strict>, z.ZodTransform<{
+    executable: string;
+    args: string[];
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    envPolicy: "ambient" | "declared-only";
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+    maxOutputBytes?: number | undefined;
+    capture: boolean;
+    stdin?: Uint8Array<ArrayBufferLike> | undefined;
+    maxStdinBytes: number;
+    onOutput?: ((bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>) | undefined;
+    onLeaderSettled?: ((event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>) | undefined;
+    onLeaderStarted?: ((event: {
+        pid: number;
+    }) => void) | undefined;
+    drainTimeoutMs?: number | undefined;
+    group: "caller" | "own";
+    stdio: "inherit" | "pipe";
+    cleanupTimeoutMs: number;
+    stop: {
+        target: "group" | "leader";
+        signal: "SIGHUP" | "SIGINT" | "SIGQUIT" | "SIGTERM" | "SIGUSR1" | "SIGUSR2";
+        graceMs: number;
+        killOn?: AbortSignal | undefined;
+    };
+    descendants: "leave" | "terminate-after-leader";
+}, {
+    executable: string;
+    args: string[];
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    envPolicy: "ambient" | "declared-only";
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+    maxOutputBytes?: number | undefined;
+    capture: boolean;
+    stdin?: Uint8Array<ArrayBufferLike> | undefined;
+    maxStdinBytes: number;
+    onOutput?: ((bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>) | undefined;
+    onLeaderSettled?: ((event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>) | undefined;
+    onLeaderStarted?: ((event: {
+        pid: number;
+    }) => void) | undefined;
+    drainTimeoutMs?: number | undefined;
+    group: "caller" | "own";
+    stdio: "inherit" | "pipe";
+    stop?: {
+        target: "group" | "leader";
+        signal: "SIGHUP" | "SIGINT" | "SIGQUIT" | "SIGTERM" | "SIGUSR1" | "SIGUSR2";
+        graceMs: number;
+        killOn?: AbortSignal | undefined;
+    } | undefined;
+    descendants?: "leave" | "terminate-after-leader" | undefined;
+    cleanupTimeoutMs: number;
+}>>;
 /**
  * Input to `runNativeCommand`: the executable and args, plus a caller signal or finite
  * timeout; capturing output also requires `maxOutputBytes`.
@@ -110,8 +183,10 @@ declare const NativeCommandLimitReasonSchema: z.ZodEnum<{
 }>;
 /**
  * Thrown by `runNativeCommand`; `code` is `COMMAND_LIMIT` (see `reason`),
- * `COMMAND_UNAVAILABLE` (could not start) or `COMMAND_CLEANUP` (handles stayed open past
- * `cleanupTimeoutMs`).
+ * `COMMAND_UNAVAILABLE` (could not start) or `COMMAND_CLEANUP` (the command's resources were not
+ * proven closed): handles stayed open past `cleanupTimeoutMs` after a stop, or the output pipes
+ * stayed open past `drainTimeoutMs` after the leader exited. `cause` holds the failure of the
+ * bound that tripped.
  */
 export declare class NativeCommandError extends Error {
     readonly code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP';

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

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,6BAA6B;;;;;;;2BAOjC,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,QAAA,MAAM,6BAA6B;;;;;;;;;;;;;;;kBAOjC,CAAC;AACH;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAqB3F,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAqBpB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAKX,uBAAuB,UAAU,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAMrE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;kBAgD5C,CAAC;AACL;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACrF,QAAA,MAAM,yBAAyB;;;;;;iBAU7B,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,8BAA8B;;;EAAwC,CAAC;AAE7E;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAezB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IAdnF,2GAA2G;IAC3G,SAAgB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,GAAG,SAAS,CAAC;IAEnF,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;KAAE,EACpF;IACF,YACE,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,KAAK,CAAA;KAAE,EAC3C;CAgBH"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,6BAA6B;;;;;;;;;;;;2BAajC,CAAC;AACH;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,QAAA,MAAM,6BAA6B;;;;;;;;;;;;;;;kBAOjC,CAAC;AACH;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAiC3F,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAqBpB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAKX,uBAAuB,UAAU,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;uDAMrE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmF3C,CAAC;AACN;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACrF,QAAA,MAAM,yBAAyB;;;;;;iBAU7B,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,8BAA8B;;;EAAwC,CAAC;AAE7E;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAezB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IAdnF,2GAA2G;IAC3G,SAAgB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,GAAG,SAAS,CAAC;IAEnF,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;KAAE,EACpF;IACF,YACE,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,KAAK,CAAA;KAAE,EAC3C;CAgBH"}

package/dist/process/group.d.ts

@@ -45,6 +45,18 @@ export declare function stopCommandLeader(stop: CommandGroupStop & {
     leader: CommandLeader;
     leaderExit: Promise<unknown>;
 }): Promise<boolean>;
+/**
+ * Stop a command that is no group leader of its own (it joined the caller's group): the
+ * policy's signal to the leader alone, a grace its exit ends, then KILL to the leader alone.
+ * Its group is the caller's and is never signalled; a leader that has already exited is never
+ * signalled again. Resolves `true` when a signal reached the leader.
+ */
+export declare function stopLeaderAlone(stop: {
+    leader: CommandLeader;
+    policy: ParsedNativeCommandStopPolicy;
+    leaderExit: Promise<unknown>;
+    force: boolean;
+}): Promise<boolean>;
 export declare function commandCleanupError(cause: unknown): NativeCommandError;
 export declare function waitForCommandClose<T>(closed: Promise<T>, timeoutMs: number): Promise<T>;
 //# sourceMappingURL=group.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAEpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAmCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,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;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAEpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAmCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,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;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}

package/dist/process/launch.d.ts

@@ -62,6 +62,11 @@ export declare function launchNativeCommand({ options, driver, onSpawn, onFailur
         kind: "exit";
         exitCode: number | null;
         signal: string | null;
+    } | {
+        kind: "stopped";
+        cause: unknown;
+        exitCode: number | null;
+        signal: string | null;
     } | {
         kind: "error";
         cause: unknown;

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

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/process/launch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/process/launch.ts"],"names":[],"mappings":"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"}

package/dist/process/output-drain.d.ts

@@ -0,0 +1,14 @@
+import { type ParsedNativeCommandOptions } from './contract.js';
+/**
+ * The reader of a command's two output channels: one combined `maxOutputBytes` budget, the
+ * captured bytes per channel and the `onOutput` sink, all under the command's lifetime signal.
+ */
+export declare function createOutputDrain(options: ParsedNativeCommandOptions, signal: AbortSignal): {
+    drain: (stream: AsyncIterable<Uint8Array>, channel: 'stdout' | 'stderr') => Promise<void>;
+    /** The captured bytes of each channel; empty unless `capture` was set. */
+    captured: () => {
+        stdout: Buffer<ArrayBuffer>;
+        stderr: Buffer<ArrayBuffer>;
+    };
+};
+//# sourceMappingURL=output-drain.d.ts.map

package/dist/process/output-drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-drain.d.ts","sourceRoot":"","sources":["../../src/process/output-drain.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,0BAA0B,EAAE,MAAM,EAAE,WAAW;oBAG3D,aAAa,CAAC,UAAU,CAAC,WAAW,QAAQ,GAAG,QAAQ;IA+BlF,0EAA0E;;QAExE,MAAM;QACN,MAAM;;EAGX"}

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

@@ -1,3 +1,4 @@
+import type { NativeCommandLaunchedProcess } from './launch.js';
 /** Only this native spawn can establish group ownership; structural PIDs cannot. */
 export declare function spawnOwnedCommand(input: {
     executable: string;
@@ -6,5 +7,13 @@ export declare function spawnOwnedCommand(input: {
     env?: NodeJS.ProcessEnv;
     group: boolean;
 }): import("node:child_process").ChildProcessWithoutNullStreams;
+/** The same ownership rule as {@link spawnOwnedCommand}, for a child that inherits stdio. */
+export declare function spawnInheritedCommand(input: {
+    executable: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    group: boolean;
+}): NativeCommandLaunchedProcess;
 export declare function ownsCommandGroup(child: object): boolean;
 //# sourceMappingURL=owned-child.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"owned-child.d.ts","sourceRoot":"","sources":["../../src/process/owned-child.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA+B,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAI1F,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;AAmDD,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,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,GAAG,4BAA4B,CAW/B;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/process/terminate.d.ts

@@ -17,6 +17,8 @@ export declare function signalCommandChild(child: SignalableChild, input: {
     leaderExit: Promise<unknown>;
     cleanupTimeoutMs: number;
     force: boolean;
+    /** The child joined the caller's group (`group: 'caller'`): only its leader is stopped. */
+    callerGroup?: boolean;
 }): Promise<boolean>;
 interface ClosableChild extends SignalableChild {
     readonly stdin: {

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

@@ -1 +1 @@
-{"version":3,"file":"terminate.d.ts","sourceRoot":"","sources":["../../src/process/terminate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,SAAS,CAAC;AAGjB,mFAAmF;AACnF,UAAU,eAAgB,SAAQ,aAAa;IAC7C,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IACL,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,6BAA6B,CAAC;IACtC,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;CAChB,GACA,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAED,UAAU,aAAc,SAAQ,eAAe;IAC7C,QAAQ,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"terminate.d.ts","sourceRoot":"","sources":["../../src/process/terminate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EACL,KAAK,aAAa,EAMnB,MAAM,SAAS,CAAC;AAGjB,mFAAmF;AACnF,UAAU,eAAgB,SAAQ,aAAa;IAC7C,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IACL,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,6BAA6B,CAAC;IACtC,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,2FAA2F;IAC3F,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED,UAAU,aAAc,SAAQ,eAAe;IAC7C,QAAQ,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,OAAO,CAAA;KAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/process/transport.d.ts

@@ -7,6 +7,11 @@ export declare function createCommandTransport(child: NativeCommandLaunchedProce
         kind: "exit";
         exitCode: number | null;
         signal: string | null;
+    } | {
+        kind: "stopped";
+        cause: unknown;
+        exitCode: number | null;
+        signal: string | null;
     } | {
         kind: "error";
         cause: unknown;

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

@@ -1 +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"}
+{"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/process.txt

@@ -213,7 +213,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.
@@ -268,13 +270,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({
@@ -284,7 +288,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.
 
 
@@ -300,26 +305,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.
@@ -574,12 +621,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/stitchkit.txt

@@ -83,12 +83,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 |
@@ -100,7 +100,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 |

package/llms/{upgrading-0.37.0-0.50.0.txt → upgrading-0.37.0-0.53.0.txt}

@@ -1,14 +1,36 @@
-# Upgrading 0.37.0 → 0.50.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.53.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.37.0 → 0.50.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides

package/llms/{upgrading-0.53.0-0.67.0.txt → upgrading-0.55.0-0.68.0.txt}

@@ -1,14 +1,64 @@
-# Upgrading 0.53.0 → 0.67.0 — stitchkit docs slice
+# Upgrading 0.55.0 → 0.68.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.53.0 → 0.67.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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.
+
 ## Released migration: 0.67.0
 
 Three application-kernel changes. Two of them fix silent failures, so the most
@@ -1150,25 +1200,3 @@ Downloaded `path` is now relative to the boundary and MIME metadata is named
 same way. Auth predicates must explicitly return `true`, `false`, or a plain
 object of context fields; replace accidental `undefined` fallthroughs with the
 intended boolean.
-
-## Released migration: 0.53.0
-
-### Realtime `emit` returns `boolean` instead of `void`
-
-Every **call site** compiles and behaves exactly as before — the return value
-is new information (`true` = accepted by the transport, `false` = dropped
-while the browser client was disconnected), not a behavior change. What breaks
-is **implementing** the interfaces: a test mock or app-side adapter of
-`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
-`RealtimeServer` whose `emit` returns `void` no longer typechecks.
-
-```ts
-// before — a void mock satisfied the interface
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
-// after — report acceptance (true is what a live server-side emit reports)
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
-```
-
-While migrating, consider replacing hand-rolled `if (client.connected)` guards
-with the new honest surface: check `client.emit(...) === false`, or observe
-drops centrally with `onDroppedEmit`.