stitchkit 0.105.0 → 0.105.2

package/CHANGELOG.md

@@ -15,6 +15,50 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.105.2] - 2026-10-06
+
+### Added
+
+- `stitchkit/process` — `runNativeCommand` takes `onLeaderStarted({ pid })`, called once right
+  after the leader exists (a throw stops the command with that error), and `drainTimeoutMs`,
+  which bounds how long the output pipes may stay open after the leader exited: a holder that
+  left the group with `setsid` otherwise keeps the command waiting until `timeoutMs` or the
+  signal, and with the bound it ends with `COMMAND_CLEANUP`.
+
+### Documentation
+
+- `stitchkit/process` — the native IO guide no longer says that `cleanupTimeoutMs` bounds the drain
+  after the leader exited; it bounds the wait after a stop, and `drainTimeoutMs` bounds the drain.
+
+## [0.105.1] - 2026-10-06
+
+### Added
+
+- `stitchkit/process` — `NativeCommandResult.descendantsStopped` reports that the group still had
+  members after the leader exited and that `descendants: 'terminate-after-leader'` stopped them,
+  so a helper ended this way is visible in the result instead of only missing afterwards.
+- `stitchkit/files/packaging` — `assetPath` accepts `[hash]`, replaced by the first 16 hex digits
+  of the addon's published SHA256, so two installed versions get different companion names
+  (`addons/darwin-arm64-[hash].node`); the loader requires exactly that name.
+
+### Fixed
+
+- `stitchkit/files` — `sweepAtomicStaging` returns `[]` for a `directory` that does not exist yet
+  instead of throwing `ENOENT`; any other listing failure still throws.
+- `stitchkit/process` — an option `runNativeCommand` does not know is refused by name, and the
+  removed `killGraceMs` names its replacement, `stop: { target: 'group', graceMs }`: a spread
+  object can carry a key the type never checked.
+
+### Documentation
+
+- `stitchkit/process` — the 0.105.0 note that a descendant leaving the group with `setsid` is
+  unaffected holds only when it has left before the leader exits: `setsid helper &` and
+  `nohup helper &` race the leader and are stopped, `setsid -f helper` survives. The native IO
+  guide shows the measured forms, how a guardian or worker that holds a child until it exits
+  maps onto `runNativeCommand`, and why a child inheriting the terminal stays a plain spawn.
+- `stitchkit/files/packaging` — calling `createNativePackaging` has to stay in the build step;
+  importing the leaf from a module that is also bundled is side-effect free.
+
 ## [0.105.0] - 2026-10-05
 
 ### ⚠️ Breaking changes

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -7,10 +7,10 @@ import {
   AgentCodingToolAuthorizationSchema2,
   AgentCodingToolPathAuthorizationSchema2,
   createAgentCodingTools2
-} from "../../index-ma963wz7.js";
+} from "../../index-sevbwsnn.js";
 import"../../index-v5ee8ath.js";
-import"../../index-cq59agna.js";
-import"../../index-g2vfg7ak.js";
+import"../../index-j4zh647a.js";
+import"../../index-3s86a7kf.js";
 import"../../index-8ks9b85e.js";
 import"../../index-gxm9rc97.js";
 import"../../index-yvfk3y36.js";

package/dist/entrypoints/agent-runtime/sandbox.js

@@ -9,9 +9,9 @@ import"../../index-r393tnfp.js";
 import"../../index-rpzewktb.js";
 import {
   createAgentCodingTools2
-} from "../../index-ma963wz7.js";
+} from "../../index-sevbwsnn.js";
 import"../../index-v5ee8ath.js";
-import"../../index-cq59agna.js";
+import"../../index-j4zh647a.js";
 import {
   COMMAND_CLEANUP_TIMEOUT_MS,
   NativeCommandError2,
@@ -19,7 +19,7 @@ import {
   nativeCommandOwner,
   terminateOwnedGroup,
   startNativeCommand
-} from "../../index-g2vfg7ak.js";
+} from "../../index-3s86a7kf.js";
 import"../../index-gxm9rc97.js";
 import {
   MAX_TIMER_MS

package/dist/entrypoints/application/directory-inbox.js

@@ -10,7 +10,7 @@ import {
   renewEntry,
   forgetMissing
 } from "../../index-msfpyy2f.js";
-import"../../index-cq59agna.js";
+import"../../index-j4zh647a.js";
 import {
   backoffDelay
 } from "../../index-g6a3na27.js";
@@ -19,7 +19,7 @@ import"../../index-azx12jgv.js";
 import"../../index-v5ee8ath.js";
 import {
   createFileStateStore2
-} from "../../index-2rc6jd9n.js";
+} from "../../index-1ptj98e0.js";
 import {
   defineManagedResource2
 } from "../../index-50ejfz75.js";
@@ -37,7 +37,7 @@ import {
 } from "../../index-m616f0yz.js";
 import {
   writeAtomicFileData
-} from "../../index-ef8gdaq0.js";
+} from "../../index-cazts87s.js";
 import {
   closeAfter,
   publishAtomicFile

package/dist/entrypoints/cli/publish.js

@@ -1,9 +1,9 @@
 import"../../index-xqhede6x.js";
-import"../../index-cq59agna.js";
+import"../../index-j4zh647a.js";
 import {
   ManagedFileError2,
   createManagedFileBoundary2
-} from "../../index-wqmvtnkp.js";
+} from "../../index-w8etpm8j.js";
 import"../../index-dsnjzb62.js";
 import"../../index-azx12jgv.js";
 import"../../index-v5ee8ath.js";
@@ -20,13 +20,13 @@ import {
   gzipCliAsset,
   decodeCliAsset,
   compareCliVersions2
-} from "../../index-szybbezc.js";
+} from "../../index-drs41arz.js";
 import {
   withExclusiveLock2
 } from "../../index-4vsby8n8.js";
 import {
   writeFileAtomic2
-} from "../../index-ef8gdaq0.js";
+} from "../../index-cazts87s.js";
 import {
   AtomicFilePublicationError2,
   assertDirectoryDurability,

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   pollUntilDone2,
   createCli2
 } from "../index-ksfagmyz.js";
-import"../index-cq59agna.js";
+import"../index-j4zh647a.js";
 import {
   AppError2
 } from "../index-j9gxbztg.js";
@@ -45,10 +45,10 @@ import {
   checkCliUpdate2,
   applyCliUpdate2,
   rollbackCliUpdate2
-} from "../index-szybbezc.js";
+} from "../index-drs41arz.js";
 import {
   writeFileAtomicSync2
-} from "../index-ef8gdaq0.js";
+} from "../index-cazts87s.js";
 import"../index-pz3y6b6g.js";
 import"../index-yvfk3y36.js";
 import {

package/dist/entrypoints/files/packaging.js

@@ -65,17 +65,20 @@ var CommonOptions = {
   platform: PlatformSchema,
   entryPath: RelativePathSchema.refine((value) => !value.includes("[") && !value.includes("]"), "Expected a fixed entry path without Bun naming templates")
 };
+var ASSET_HASH_TOKEN = "[hash]";
+var ASSET_HASH_LENGTH = 16;
+var AssetPathSchema = RelativePathSchema.refine((value) => !/[[\]]/.test(value.replaceAll(ASSET_HASH_TOKEN, "")), "Expected an addon path whose only template is [hash]");
 var SingleOptionsSchema = z2.object({
   ...CommonOptions,
   architecture: z2.string().min(1),
   delivery: z2.enum(["companion", "embedded"]),
-  assetPath: RelativePathSchema
+  assetPath: AssetPathSchema
 });
 var MultipleOptionsSchema = z2.object({
   ...CommonOptions,
   architecture: z2.array(z2.string().min(1)).refine((targets) => targets.length > 0),
   delivery: z2.literal("companion"),
-  assetPath: z2.record(z2.string().min(1), RelativePathSchema)
+  assetPath: z2.record(z2.string().min(1), AssetPathSchema)
 });
 var OptionsSchema = z2.union([SingleOptionsSchema, MultipleOptionsSchema]).check((ctx) => {
   const input = ctx.value;
@@ -220,13 +223,16 @@ function createNativePackaging(options) {
   const specifiers = {};
   const embedded = new Map;
   for (const architecture of architectures) {
-    const outputPath = typeof input.assetPath === "string" ? input.assetPath : input.assetPath[architecture];
-    if (!outputPath)
+    const template = typeof input.assetPath === "string" ? input.assetPath : input.assetPath[architecture];
+    if (!template)
       throw new Error("Declared architecture has no output path");
     const verified = readVerifiedAsset(root, published.assets[architecture], input.platform, architecture);
     if ("refusal" in verified)
       return verified.refusal;
     const { sourcePath, bytes, size, sha256 } = verified;
+    const outputPath = template.replaceAll(ASSET_HASH_TOKEN, sha256.slice(0, ASSET_HASH_LENGTH));
+    if (assets.some((asset) => asset.outputPath === outputPath))
+      throw new Error("Addons must have distinct output paths");
     if (input.delivery === "embedded")
       embedded.set(sourcePath, new Uint8Array(bytes));
     const outputSpecifier = relative(dirname(input.entryPath), outputPath).split("\\").join("/");

package/dist/entrypoints/files.js

@@ -6,11 +6,11 @@ import {
   stagingPath,
   isAtomicStagingName2,
   sweepAtomicStaging2
-} from "../index-cq59agna.js";
+} from "../index-j4zh647a.js";
 import {
   ManagedFileError2,
   createManagedFileBoundary2
-} from "../index-wqmvtnkp.js";
+} from "../index-w8etpm8j.js";
 import {
   AppError2
 } from "../index-j9gxbztg.js";
@@ -24,7 +24,7 @@ import {
 import {
   writeFileAtomic2,
   writeFileAtomicSync2
-} from "../index-ef8gdaq0.js";
+} from "../index-cazts87s.js";
 import {
   AtomicFilePublicationError2
 } from "../index-b56nnscm.js";

package/dist/entrypoints/process.js

@@ -7,7 +7,7 @@ import {
 import {
   NativeCommandError2,
   startNativeCommand
-} from "../index-g2vfg7ak.js";
+} from "../index-3s86a7kf.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;

package/dist/entrypoints/server.js

@@ -1,10 +1,10 @@
-import"../index-cq59agna.js";
+import"../index-j4zh647a.js";
 import"../index-dsnjzb62.js";
 import"../index-azx12jgv.js";
 import"../index-v5ee8ath.js";
 import {
   createFileStateStore2
-} from "../index-2rc6jd9n.js";
+} from "../index-1ptj98e0.js";
 import {
   AppError2,
   notFound2,
@@ -96,7 +96,7 @@ import {
   isWithinDir2,
   realPathWithinDir
 } from "../index-5cc6r990.js";
-import"../index-ef8gdaq0.js";
+import"../index-cazts87s.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS2,
   DEFAULT_CORS_EXPOSE_HEADERS2,

package/dist/entrypoints/telegram.js

@@ -8,7 +8,7 @@ import {
   TELEGRAM_SEND_FAILURE_REASONS2,
   classifyTelegramSendFailure2
 } from "../index-e05cjgtf.js";
-import"../index-cq59agna.js";
+import"../index-j4zh647a.js";
 import {
   attemptExclusiveLock
 } from "../index-dsnjzb62.js";
@@ -23,7 +23,7 @@ import {
 } from "../index-b0kddvzw.js";
 import {
   writeFileAtomic2
-} from "../index-ef8gdaq0.js";
+} from "../index-cazts87s.js";
 import {
   MAX_TIMER_MS,
   sleep

package/dist/entrypoints/tools.js

@@ -85,10 +85,10 @@ import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2
 } from "../index-xqhede6x.js";
-import"../index-cq59agna.js";
+import"../index-j4zh647a.js";
 import {
   ManagedFileError2
-} from "../index-wqmvtnkp.js";
+} from "../index-w8etpm8j.js";
 import {
   fetchGuarded,
   fetchPinnedDocument,
@@ -102,7 +102,7 @@ import {
   contractOnlyService,
   mediaTypeEssence
 } from "../index-cmzvhhtd.js";
-import"../index-ef8gdaq0.js";
+import"../index-cazts87s.js";
 import {
   collectToolSurface
 } from "../index-pz3y6b6g.js";

package/dist/files/native-packaging.d.ts.map

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

package/dist/{index-2rc6jd9n.js → index-1ptj98e0.js}

@@ -6,7 +6,7 @@ import {
 } from "./index-m616f0yz.js";
 import {
   writeAtomicFileData
-} from "./index-ef8gdaq0.js";
+} from "./index-cazts87s.js";
 import {
   publishAtomicFile
 } from "./index-b56nnscm.js";

package/dist/{index-g2vfg7ak.js → index-3s86a7kf.js}

@@ -27,6 +27,16 @@ var NativeCommandStopPolicySchema = z.strictObject({
   graceMs: z.number().int().nonnegative().max(MAX_COMMAND_STOP_GRACE_MS),
   killOn: z.custom((v) => v instanceof AbortSignal).optional()
 });
+var REMOVED_NATIVE_COMMAND_OPTIONS = {
+  killGraceMs: "stop: { target: 'group', graceMs } (removed in 0.105.0)"
+};
+function unknownOptionMessage(keys) {
+  return keys.map((key) => {
+    const name = String(key);
+    const replacement = Object.hasOwn(REMOVED_NATIVE_COMMAND_OPTIONS, name) ? REMOVED_NATIVE_COMMAND_OPTIONS[name] : undefined;
+    return replacement === undefined ? `Unknown runNativeCommand option ${name}` : `Unknown runNativeCommand option ${name}; use ${replacement}`;
+  }).join("; ");
+}
 var NativeCommandOptionsSchema = z.strictObject({
   executable: z.string().min(1),
   args: z.array(z.string()).default([]),
@@ -41,6 +51,8 @@ var NativeCommandOptionsSchema = z.strictObject({
   maxStdinBytes: z.number().int().positive().default(1024 * 1024),
   onOutput: z.custom((v) => typeof v === "function").optional(),
   onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
+  onLeaderStarted: z.custom((v) => typeof v === "function").optional(),
+  drainTimeoutMs: z.number().int().positive().max(MAX_TIMER_MS).optional(),
   stop: NativeCommandStopPolicySchema.default({
     target: "group",
     signal: "SIGTERM",
@@ -48,6 +60,8 @@ var NativeCommandOptionsSchema = z.strictObject({
   }),
   descendants: z.enum(["terminate-after-leader", "leave"]).default("terminate-after-leader"),
   cleanupTimeoutMs: z.number().int().positive().max(30000).default(COMMAND_CLEANUP_TIMEOUT_MS)
+}, {
+  error: (issue) => issue.code === "unrecognized_keys" ? unknownOptionMessage(issue.keys) : undefined
 }).check((ctx) => {
   const input = ctx.value;
   if (!input.signal && input.timeoutMs === undefined)
@@ -72,6 +86,7 @@ var NativeCommandOptionsSchema = z.strictObject({
 var NativeCommandResultSchema = z.object({
   exitCode: z.number().int().nullable(),
   signal: z.string().nullable(),
+  descendantsStopped: z.boolean(),
   stdout: z.instanceof(Uint8Array),
   stderr: z.instanceof(Uint8Array)
 });
@@ -158,12 +173,10 @@ async function signalUntilSettled(pid, signal, deadline) {
 async function stopCommandGroup(stop) {
   const { pid, policy } = stop;
   const deadline = performance.now() + policy.graceMs + stop.cleanupTimeoutMs;
-  if (stop.force || policy.killOn?.aborted) {
-    await signalUntilSettled(pid, "SIGKILL", deadline);
-    return;
-  }
+  if (stop.force || policy.killOn?.aborted)
+    return signalUntilSettled(pid, "SIGKILL", deadline);
   if (!await signalUntilSettled(pid, policy.signal, deadline))
-    return;
+    return false;
   const until = performance.now() + policy.graceMs;
   let interval = 10;
   let present = exists(pid);
@@ -176,14 +189,17 @@ async function stopCommandGroup(stop) {
   }
   if (present)
     await signalUntilSettled(pid, "SIGKILL", deadline);
+  return true;
 }
 async function stopCommandLeader(stop) {
   const { pid, policy, leader } = stop;
   const deadline = performance.now() + policy.graceMs + stop.cleanupTimeoutMs;
   const running = () => leader.exitCode === null && leader.signalCode === null;
+  let signalled = false;
   if (!stop.force && !policy.killOn?.aborted && pid !== undefined && running()) {
     try {
       process.kill(pid, policy.signal);
+      signalled = true;
     } catch (error) {
       if (!isErrno(error, "ESRCH"))
         throw error;
@@ -198,7 +214,7 @@ async function stopCommandLeader(stop) {
     policy.killOn?.removeEventListener("abort", end);
     grace.abort();
   }
-  await signalUntilSettled(pid, "SIGKILL", deadline);
+  return await signalUntilSettled(pid, "SIGKILL", deadline) || signalled;
 }
 function commandCleanupError(cause) {
   return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
@@ -616,8 +632,11 @@ function signalCommandChild(child, input) {
     return input.policy.target === "leader" ? stopCommandLeader({ ...stop, leader: child, leaderExit: input.leaderExit }) : stopCommandGroup(stop);
   }
   return Promise.resolve().then(() => {
-    if (child.exitCode === null && child.signalCode === null && !child.kill("SIGKILL"))
+    if (child.exitCode !== null || child.signalCode !== null)
+      return false;
+    if (!child.kill("SIGKILL"))
       throw new Error("Command leader termination was refused");
+    return true;
   });
 }
 async function terminateOwnedGroup(child, closed, cleanupTimeoutMs) {
@@ -677,7 +696,7 @@ function startNativeCommand(input, onSpawn, driver) {
   });
   const signalOwned = (force = driver?.force) => {
     if (!acquired)
-      return Promise.resolve();
+      return Promise.resolve(false);
     return signalCommandChild(acquired.child, {
       group: driver?.group !== false,
       policy: options.stop,
@@ -731,7 +750,7 @@ function startNativeCommand(input, onSpawn, driver) {
   const stderr = [];
   let total = 0;
   const { stdout: output, stderr: errorOutput, leader, closed } = launched;
-  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs, controller);
+  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs ?? options.drainTimeoutMs, controller);
   const drain = async (stream, channel, captured) => {
     for await (const chunk of stream) {
       if (controller.signal.aborted)
@@ -757,6 +776,7 @@ function startNativeCommand(input, onSpawn, driver) {
         }
     }
   };
+  let descendantsStopped = false;
   const settleLeader = async (event) => {
     await settle(event);
     if (controller.signal.aborted)
@@ -764,7 +784,7 @@ function startNativeCommand(input, onSpawn, driver) {
     if (options.descendants !== "terminate-after-leader" || event.kind !== "exit")
       return;
     try {
-      await signalOwned();
+      descendantsStopped = await signalOwned();
     } catch (cause) {
       throw commandCleanupError(cause);
     }
@@ -772,6 +792,9 @@ function startNativeCommand(input, onSpawn, driver) {
   const run = (async () => {
     try {
       launched.start();
+      const pid = acquired?.child.pid;
+      if (pid !== undefined)
+        options.onLeaderStarted?.({ pid });
       const drains = Promise.all([
         drain(output, "stdout", stdout),
         drain(errorOutput, "stderr", stderr)
@@ -780,7 +803,12 @@ function startNativeCommand(input, onSpawn, driver) {
       const status = await raceAbort(closed, controller.signal);
       if (spawnFailure !== undefined)
         throw spawnFailure;
-      return { ...status, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) };
+      return {
+        ...status,
+        descendantsStopped,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr)
+      };
     } catch (error) {
       controller.abort(error);
       await cleanupNativeCommand({

package/dist/{index-ef8gdaq0.js → index-cazts87s.js}

@@ -1,6 +1,6 @@
 import {
   stagingPath
-} from "./index-cq59agna.js";
+} from "./index-j4zh647a.js";
 import {
   closeAfter,
   closeAfterSync,

package/dist/{index-szybbezc.js → index-drs41arz.js}

@@ -11,7 +11,7 @@ import {
 } from "./index-b0kddvzw.js";
 import {
   writeFileAtomicSync2
-} from "./index-ef8gdaq0.js";
+} from "./index-cazts87s.js";
 import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";

package/dist/{index-cq59agna.js → index-j4zh647a.js}

@@ -29,7 +29,15 @@ async function sweepAtomicStaging2(options) {
   signal?.throwIfAborted();
   const cutoff = Date.now() - olderThanMs;
   const removed = [];
-  for (const name of await readdir(directory)) {
+  let names;
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (isMissing(error))
+      return removed;
+    throw error;
+  }
+  for (const name of names) {
     signal?.throwIfAborted();
     if (!isAtomicStagingName2(name))
       continue;

package/dist/{index-ma963wz7.js → index-sevbwsnn.js}

@@ -7,12 +7,12 @@ import {
 } from "./index-v5ee8ath.js";
 import {
   stagingName
-} from "./index-cq59agna.js";
+} from "./index-j4zh647a.js";
 import {
   NativeCommandError2,
   CommandStopped,
   startNativeCommand
-} from "./index-g2vfg7ak.js";
+} from "./index-3s86a7kf.js";
 import {
   probeAgentProcessSandboxOutcome,
   missingSandboxRestrictions2,

package/dist/{index-wqmvtnkp.js → index-w8etpm8j.js}

@@ -15,7 +15,7 @@ import {
 import {
   writeAllBytes,
   writeAtomicFileStaged
-} from "./index-ef8gdaq0.js";
+} from "./index-cazts87s.js";
 import {
   AtomicFilePublicationError2
 } from "./index-b56nnscm.js";

package/dist/internal/atomic-staging.d.ts

@@ -40,7 +40,8 @@ export interface SweepAtomicStagingOptions {
  * Remove the abandoned staging files of atomic writes from one directory and return their
  * names. Only regular files matching {@link isAtomicStagingName} and older than `olderThanMs`
  * are removed; a symlink, a directory or any other entry is left alone, and nothing is
- * followed or recursed into.
+ * followed or recursed into. A `directory` that does not exist holds nothing to sweep and
+ * yields `[]`; any other listing failure (a file in its place, a denied read) throws.
  */
 export declare function sweepAtomicStaging(options: SweepAtomicStagingOptions): Promise<string[]>;
 //# sourceMappingURL=atomic-staging.d.ts.map

package/dist/internal/atomic-staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-staging.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,mGAAmG;AACnG,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAQD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBnB"}
+{"version":3,"file":"atomic-staging.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,mGAAmG;AACnG,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAQD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB"}

package/dist/process/cleanup.d.ts

@@ -11,7 +11,7 @@ export declare function cleanupNativeCommand(input: {
     transport?: NativeCommandTransport;
     settle: (event: NativeCommandSettlement) => Promise<void>;
     event?: NativeCommandSettlement;
-    signal: () => Promise<void>;
+    signal: () => Promise<unknown>;
     timeoutMs: number;
 }): Promise<void>;
 //# sourceMappingURL=cleanup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/process/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/process/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}

package/dist/process/command-lifetime.d.ts

@@ -8,12 +8,13 @@ export declare function createCommandLifetime(input: {
     result: Promise<NativeCommandResult>;
     controller: AbortController;
     finished: () => boolean;
-    signal: () => Promise<void>;
+    signal: () => Promise<unknown>;
     cleanupTimeoutMs: number;
 }): {
     result: Promise<{
         exitCode: number | null;
         signal: string | null;
+        descendantsStopped: boolean;
         stdout: Uint8Array<ArrayBuffer>;
         stderr: Uint8Array<ArrayBuffer>;
     }>;

package/dist/process/command-lifetime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-lifetime.d.ts","sourceRoot":"","sources":["../../src/process/command-lifetime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAG1E,gFAAgF;AAChF,qBAAa,cAAe,SAAQ,YAAY;IAC9C,cAEC;CACF;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrC,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;IAKG,MAAM;;;;;;IACA,SAAS;IAoBT,IAAI;EAKb"}
+{"version":3,"file":"command-lifetime.d.ts","sourceRoot":"","sources":["../../src/process/command-lifetime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAG1E,gFAAgF;AAChF,qBAAa,cAAe,SAAQ,YAAY;IAC9C,cAEC;CACF;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrC,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;IAKG,MAAM;;;;;;;IACA,SAAS;IAoBT,IAAI;EAKb"}

package/dist/process/command-owner.d.ts

@@ -6,6 +6,7 @@ export declare function startNativeCommand(input: NativeCommandOptions, onSpawn?
     result: Promise<{
         exitCode: number | null;
         signal: string | null;
+        descendantsStopped: boolean;
         stdout: Uint8Array<ArrayBuffer>;
         stderr: Uint8Array<ArrayBuffer>;
     }>;

package/dist/process/command-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-owner.d.ts","sourceRoot":"","sources":["../../src/process/command-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAIzE,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAMlB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,yBAAyB;;;;;;;;;EAyLnC"}
+{"version":3,"file":"command-owner.d.ts","sourceRoot":"","sources":["../../src/process/command-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAIzE,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAMlB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,yBAAyB;;;;;;;;;;EAiMnC"}

package/dist/process/contract.d.ts

@@ -58,6 +58,12 @@ export declare const NativeCommandOptionsSchema: z.ZodObject<{
     maxStdinBytes: z.ZodDefault<z.ZodNumber>;
     onOutput: z.ZodOptional<z.ZodCustom<(bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>, (bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>>>;
     onLeaderSettled: z.ZodOptional<z.ZodCustom<(event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>, (event: NativeCommandSettlement, signal: AbortSignal) => void | Promise<void>>>;
+    onLeaderStarted: z.ZodOptional<z.ZodCustom<(event: {
+        pid: number;
+    }) => void, (event: {
+        pid: number;
+    }) => void>>;
+    drainTimeoutMs: z.ZodOptional<z.ZodNumber>;
     stop: z.ZodDefault<z.ZodObject<{
         target: z.ZodEnum<{
             group: "group";
@@ -89,12 +95,13 @@ export type ParsedNativeCommandOptions = z.output<typeof NativeCommandOptionsSch
 declare const NativeCommandResultSchema: z.ZodObject<{
     exitCode: z.ZodNullable<z.ZodNumber>;
     signal: z.ZodNullable<z.ZodString>;
+    descendantsStopped: z.ZodBoolean;
     stdout: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
     stderr: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
 }, z.core.$strip>;
 /**
- * Exit code, signal and captured stdout and stderr bytes of a finished command; the buffers
- * stay empty unless `capture` was set.
+ * Exit code, signal, whether descendants were stopped after the leader exited, and captured
+ * stdout and stderr bytes of a finished command; the buffers stay empty unless `capture` was set.
  */
 export type NativeCommandResult = z.infer<typeof NativeCommandResultSchema>;
 declare const NativeCommandLimitReasonSchema: z.ZodEnum<{

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;AAE3F,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAoBtB,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;;;;;;;;;;;;;;;;;;;;;;kBAuCvF,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;;;;;iBAK7B,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;;;;;;;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"}

package/dist/process/group.d.ts

@@ -23,8 +23,9 @@ export interface CommandGroupStop {
  * A group still visible after the grace (including members holding a pipe after
  * the leader exited, or Darwin zombies awaiting the reaper) is killed. The probe
  * backs off to 250 ms, so a grace of an hour costs a few thousand probes, not millions.
+ * Resolves `true` when the group still had a member to receive the first signal.
  */
-export declare function stopCommandGroup(stop: CommandGroupStop): Promise<void>;
+export declare function stopCommandGroup(stop: CommandGroupStop): Promise<boolean>;
 /** The leader of a stop with `target: 'leader'`: its exit state and the promise of its exit. */
 export interface CommandLeader {
     readonly pid?: number;
@@ -38,11 +39,12 @@ export interface CommandLeader {
  * The leader's exit ends the grace at once: the rest of the group are processes the leader
  * left behind, and nothing in them was asked to cooperate. A leader that has already
  * exited is not signalled again, because its pid may be reused once it was reaped.
+ * Resolves `true` when the leader or a member of its group received a signal.
  */
 export declare function stopCommandLeader(stop: CommandGroupStop & {
     leader: CommandLeader;
     leaderExit: Promise<unknown>;
-}): Promise<void>;
+}): 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;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB5E;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;;;;;;;GAOG;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,IAAI,CAAC,CAoBf;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,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/terminate.d.ts

@@ -7,7 +7,8 @@ interface SignalableChild extends CommandLeader {
 /**
  * Deliver the stop signals to `child` by its stop policy. A child this package spawned as a
  * group leader is stopped as a group (`target: 'group'`) or leader first (`'leader'`); any
- * other child is only a leader, killed while it still runs.
+ * other child is only a leader, killed while it still runs. Resolves `true` when a signal
+ * reached a process.
  */
 export declare function signalCommandChild(child: SignalableChild, input: {
     group: boolean;
@@ -16,7 +17,7 @@ export declare function signalCommandChild(child: SignalableChild, input: {
     leaderExit: Promise<unknown>;
     cleanupTimeoutMs: number;
     force: boolean;
-}): Promise<void>;
+}): Promise<boolean>;
 interface ClosableChild extends SignalableChild {
     readonly stdin: {
         destroy(): unknown;

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;;;;GAIG;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,IAAI,CAAC,CAgBf;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,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"}

package/llms/files-packaging.txt

@@ -20,6 +20,8 @@ It resolves the installed package's target/version, reads each selected addon on
 against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
 written when Stitchkit is built). Call it once per build and reuse the result.
 `platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
+`assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of the addon's
+published SHA256;
 `platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
 The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
 `missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or

package/llms/files.txt

@@ -31,7 +31,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running. A process killed before publication leaves its staging file; sweeping it is the caller's job |
 | `isAtomicStagingName` | function | true for a staging file name of an atomic write of this library (`.stitchkit-<24 lowercase hex>.tmp`, also used by the managed writer and the chunk spool); the form is a stable contract, and changing it is a breaking change ([ADR 0242](../decisions/0242-atomic-staging-name-is-a-public-contract.md)) |
-| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names |
+| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names, `[]` for a `directory` that does not exist |
 | `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; the lock is published with its owner already recorded (temporary file plus hard link), so a stalled holder is never displaced; a legacy empty lock file is taken by age only when `ownerlessGraceMs` is a number (default `null`: never; an abandoned empty reclaim guard is taken after 5 000 ms unless a value is set); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |

package/llms/process.txt

@@ -68,7 +68,8 @@ The bytes are staged beside the target under `.stitchkit-<24 lowercase hex>.tmp`
 `writeFileAtomic`, `writeFileAtomicSync`, the managed writer and the chunk spool. A process killed
 between the staging and the publication (SIGKILL, OOM, power loss) leaves that file behind, and no
 later write removes it: a random name alone cannot tell an abandoned write from one in flight.
-Removing it is the caller's responsibility:
+Removing it is the caller's responsibility. A directory that does not exist yet has nothing to
+sweep and yields `[]`; a file standing where the directory should be, or a denied listing, throws:
 
 ```ts
 import { isAtomicStagingName, sweepAtomicStaging } from 'stitchkit/files'
@@ -197,7 +198,7 @@ permanent refusal is kept in the cause. The close of every owned pipe and the le
 observed separately, including the absence of a shared `child.close` during teardown. The caller or
 sink cause is kept; a cleanup failure is a `NativeCommandError` with `COMMAND_CLEANUP` and an
 `AggregateError` cause. Even an exited parent does not exclude a helper that holds a pipe. Windows
-refuses with `COMMAND_UNAVAILABLE`; a descendant that leaves the group on its own with `setsid` is
+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.
 
 ### Stopping a command: the `stop` policy
@@ -252,13 +253,28 @@ successfully:
 
 | `descendants` | After the leader exits |
 |---|---|
-| `'terminate-after-leader'` (the default) | The group is stopped right after `onLeaderSettled` returns and before the pipes drain: with `target: 'group'` by the same signal, grace, KILL sequence as cancellation; with `target: 'leader'` by KILL at once, since the leader has already exited. Descendants that left the group with `setsid` stay out of reach. |
+| `'terminate-after-leader'` (the default) | The group is stopped right after `onLeaderSettled` returns and before the pipes drain: with `target: 'group'` by the same signal, grace, KILL sequence as cancellation; with `target: 'leader'` by KILL at once, since the leader has already exited. A descendant that had already left the group with `setsid` when the leader exited stays out of reach. |
 | `'leave'` | Nothing. A helper started with its stdio detached keeps running. One that inherited stdout or stderr keeps the pipes open, and the command then waits for it until its deadline or abort. |
 
 Omitting the option means `'terminate-after-leader'`: a command does not leak the helpers it
-started. A real daemon detaches into its own session (`setsid`, as `daemon(3)` does), is no member
-of the group and is unaffected. Declare `'leave'` only for a helper that has to outlive the
-command while staying in its group:
+started. The result's `descendantsStopped` is `true` when the group still had members after the
+leader exited and they were stopped, so a helper that was ended this way is visible to the caller
+rather than only missing afterwards; under `'leave'` it is always `false`.
+
+A real daemon detaches into its own session (`setsid`, as `daemon(3)` does), is no member of the
+group and is unaffected, provided it has left the group **before the leader exits**. Leaving is
+the daemon's own system call, and the group is stopped as soon as the leader's exit is observed,
+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 helper &`, `(setsid helper &)`, `nohup helper &` | stopped: the leader usually exits before the background job has left the group |
+| 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:
 
 ```ts
 await runNativeCommand({
@@ -279,7 +295,21 @@ regular-file read becomes `files.read`; JSON and schema parsing, receipt conflic
 and application locks stay with the application. A spawn, drain, capture and cancellation wrapper
 becomes `runNativeCommand`; shell policy, command admission, logging, redaction, the bytes-to-text
 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. Importing one leaf does not make
+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
 installing the whole npm package smaller; choose a dependency after measuring packed size and its
 dependency closure.
 
@@ -407,7 +437,11 @@ package was built. A ready asset carries those verified `bytes` with the publish
 `sha256`; its Bun-compatible plugin integrates the same bytes with the same lazy native loader.
 Each call reads and hashes the selected addons, so call it once per build and reuse the result.
 The leaf is evolving. It requires no optional peer or Bun ambient declarations for Node imports.
-It must run unbundled from its installed package, never from an application's runtime artifact.
+Calling it must happen in a process that runs it from its installed package: it locates the
+package's `native-assets.json` beside its own file and throws `Native packaging must run from its
+installed Stitchkit package` anywhere else, such as inside an application's runtime artifact.
+Importing the leaf is side-effect free (it loads no addon and reads no file), so a module that
+both builds and is bundled may import it; only the call has to stay in the build step.
 
 ```ts
 import { createNativePackaging } from 'stitchkit/files/packaging'
@@ -434,7 +468,11 @@ for (const asset of native.assets) {
 ```
 
 `entryPath` and `assetPath` are relative paths inside the application's output root, without
-absolute paths, traversal or overlapping file/directory paths. `entryPath` is fixed, without
+absolute paths, traversal or overlapping file/directory paths. `assetPath` may contain `[hash]`,
+which becomes the first 16 hex digits of that addon's published SHA256: the digest is known before
+the build, so `addons/darwin-arm64-[hash].node` gives two installed versions of the package
+different companion names, and the loader requires exactly that name. It is the only template an
+addon path accepts. `entryPath` is fixed, without
 Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
 and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
 Choose any application layout; the framework does not prescribe an app directory or installer.
@@ -536,9 +574,9 @@ 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'`) |
+| `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 |
 | `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 and captured stdout/stderr bytes |
+| `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 |
 
 | `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 |

package/llms-full.txt

@@ -8210,7 +8210,8 @@ The bytes are staged beside the target under `.stitchkit-<24 lowercase hex>.tmp`
 `writeFileAtomic`, `writeFileAtomicSync`, the managed writer and the chunk spool. A process killed
 between the staging and the publication (SIGKILL, OOM, power loss) leaves that file behind, and no
 later write removes it: a random name alone cannot tell an abandoned write from one in flight.
-Removing it is the caller's responsibility:
+Removing it is the caller's responsibility. A directory that does not exist yet has nothing to
+sweep and yields `[]`; a file standing where the directory should be, or a denied listing, throws:
 
 ```ts
 import { isAtomicStagingName, sweepAtomicStaging } from 'stitchkit/files'
@@ -8339,7 +8340,7 @@ permanent refusal is kept in the cause. The close of every owned pipe and the le
 observed separately, including the absence of a shared `child.close` during teardown. The caller or
 sink cause is kept; a cleanup failure is a `NativeCommandError` with `COMMAND_CLEANUP` and an
 `AggregateError` cause. Even an exited parent does not exclude a helper that holds a pipe. Windows
-refuses with `COMMAND_UNAVAILABLE`; a descendant that leaves the group on its own with `setsid` is
+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.
 
 ### Stopping a command: the `stop` policy
@@ -8394,13 +8395,28 @@ successfully:
 
 | `descendants` | After the leader exits |
 |---|---|
-| `'terminate-after-leader'` (the default) | The group is stopped right after `onLeaderSettled` returns and before the pipes drain: with `target: 'group'` by the same signal, grace, KILL sequence as cancellation; with `target: 'leader'` by KILL at once, since the leader has already exited. Descendants that left the group with `setsid` stay out of reach. |
+| `'terminate-after-leader'` (the default) | The group is stopped right after `onLeaderSettled` returns and before the pipes drain: with `target: 'group'` by the same signal, grace, KILL sequence as cancellation; with `target: 'leader'` by KILL at once, since the leader has already exited. A descendant that had already left the group with `setsid` when the leader exited stays out of reach. |
 | `'leave'` | Nothing. A helper started with its stdio detached keeps running. One that inherited stdout or stderr keeps the pipes open, and the command then waits for it until its deadline or abort. |
 
 Omitting the option means `'terminate-after-leader'`: a command does not leak the helpers it
-started. A real daemon detaches into its own session (`setsid`, as `daemon(3)` does), is no member
-of the group and is unaffected. Declare `'leave'` only for a helper that has to outlive the
-command while staying in its group:
+started. The result's `descendantsStopped` is `true` when the group still had members after the
+leader exited and they were stopped, so a helper that was ended this way is visible to the caller
+rather than only missing afterwards; under `'leave'` it is always `false`.
+
+A real daemon detaches into its own session (`setsid`, as `daemon(3)` does), is no member of the
+group and is unaffected, provided it has left the group **before the leader exits**. Leaving is
+the daemon's own system call, and the group is stopped as soon as the leader's exit is observed,
+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 helper &`, `(setsid helper &)`, `nohup helper &` | stopped: the leader usually exits before the background job has left the group |
+| 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:
 
 ```ts
 await runNativeCommand({
@@ -8421,7 +8437,21 @@ regular-file read becomes `files.read`; JSON and schema parsing, receipt conflic
 and application locks stay with the application. A spawn, drain, capture and cancellation wrapper
 becomes `runNativeCommand`; shell policy, command admission, logging, redaction, the bytes-to-text
 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. Importing one leaf does not make
+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
 installing the whole npm package smaller; choose a dependency after measuring packed size and its
 dependency closure.
 
@@ -8549,7 +8579,11 @@ package was built. A ready asset carries those verified `bytes` with the publish
 `sha256`; its Bun-compatible plugin integrates the same bytes with the same lazy native loader.
 Each call reads and hashes the selected addons, so call it once per build and reuse the result.
 The leaf is evolving. It requires no optional peer or Bun ambient declarations for Node imports.
-It must run unbundled from its installed package, never from an application's runtime artifact.
+Calling it must happen in a process that runs it from its installed package: it locates the
+package's `native-assets.json` beside its own file and throws `Native packaging must run from its
+installed Stitchkit package` anywhere else, such as inside an application's runtime artifact.
+Importing the leaf is side-effect free (it loads no addon and reads no file), so a module that
+both builds and is bundled may import it; only the call has to stay in the build step.
 
 ```ts
 import { createNativePackaging } from 'stitchkit/files/packaging'
@@ -8576,7 +8610,11 @@ for (const asset of native.assets) {
 ```
 
 `entryPath` and `assetPath` are relative paths inside the application's output root, without
-absolute paths, traversal or overlapping file/directory paths. `entryPath` is fixed, without
+absolute paths, traversal or overlapping file/directory paths. `assetPath` may contain `[hash]`,
+which becomes the first 16 hex digits of that addon's published SHA256: the digest is known before
+the build, so `addons/darwin-arm64-[hash].node` gives two installed versions of the package
+different companion names, and the loader requires exactly that name. It is the only template an
+addon path accepts. `entryPath` is fixed, without
 Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
 and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
 Choose any application layout; the framework does not prescribe an app directory or installer.
@@ -22039,7 +22077,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running. A process killed before publication leaves its staging file; sweeping it is the caller's job |
 | `isAtomicStagingName` | function | true for a staging file name of an atomic write of this library (`.stitchkit-<24 lowercase hex>.tmp`, also used by the managed writer and the chunk spool); the form is a stable contract, and changing it is a breaking change ([ADR 0242](../decisions/0242-atomic-staging-name-is-a-public-contract.md)) |
-| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names |
+| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names, `[]` for a `directory` that does not exist |
 | `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; the lock is published with its owner already recorded (temporary file plus hard link), so a stalled holder is never displaced; a legacy empty lock file is taken by age only when `ownerlessGraceMs` is a number (default `null`: never; an abandoned empty reclaim guard is taken after 5 000 ms unless a value is set); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
@@ -22608,9 +22646,9 @@ 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'`) |
+| `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 |
 | `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 and captured stdout/stderr bytes |
+| `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 |
 
 | `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 |
@@ -22626,6 +22664,8 @@ It resolves the installed package's target/version, reads each selected addon on
 against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
 written when Stitchkit is built). Call it once per build and reuse the result.
 `platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
+`assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of the addon's
+published SHA256;
 `platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
 The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
 `missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or

package/llms.txt

@@ -56,8 +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) 32.8 KB
-- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 2.7 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 36.2 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.105.0",
+  "version": "0.105.2",
   "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",