stitchkit 0.103.9 → 0.103.10

package/CHANGELOG.md

@@ -15,6 +15,14 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.103.10] - 2026-10-01
+
+### Added
+
+- `stitchkit/process`: `onLeaderSettled` observes launcher exit before inherited-pipe drain and settles resource scopes once on terminal failure; callbacks have bounded cancellation and preserve initial causes. Public process identity observation/probing preserves unavailable evidence and its cause from the existing Linux/Darwin owner.
+- `stitchkit/files`: `ownerlessGraceMs: null` explicitly refuses age-based reclaim of unknown locks and guards; exact requested lock permissions survive restrictive umask, and failed descriptor setup cannot remove a replacement inode.
+- Document and qualify neutral library bundling from public imports and published declarations with Zod as its only runtime peer; full-kernel install remains a build-time choice.
+
 ## [0.103.9] - 2026-10-01
 
 ### Added

package/dist/agent-runtime/store-conformance-lifecycle.d.ts

@@ -133,6 +133,11 @@ export declare function fencingPhase(store: AgentRuntimeStore, conversationId: s
                 parts: ({
                     type: "text";
                     text: string;
+                } | {
+                    type: "file";
+                    mediaType: string;
+                    reference: string;
+                    filename?: string | undefined;
                 } | {
                     type: "reasoning";
                     text: string;
@@ -141,11 +146,6 @@ export declare function fencingPhase(store: AgentRuntimeStore, conversationId: s
                         provider: string;
                         data: Record<string, import("zod").JSONType>;
                     } | undefined;
-                } | {
-                    type: "file";
-                    mediaType: string;
-                    reference: string;
-                    filename?: string | undefined;
                 } | {
                     type: "source";
                     sourceId: string;
@@ -313,6 +313,11 @@ export declare function fencingPhase(store: AgentRuntimeStore, conversationId: s
         parts: ({
             type: "text";
             text: string;
+        } | {
+            type: "file";
+            mediaType: string;
+            reference: string;
+            filename?: string | undefined;
         } | {
             type: "reasoning";
             text: string;
@@ -321,11 +326,6 @@ export declare function fencingPhase(store: AgentRuntimeStore, conversationId: s
                 provider: string;
                 data: Record<string, import("zod").JSONType>;
             } | undefined;
-        } | {
-            type: "file";
-            mediaType: string;
-            reference: string;
-            filename?: string | undefined;
         } | {
             type: "source";
             sourceId: string;

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

@@ -13,7 +13,7 @@ import {
 import {
   NativeCommandError2,
   startNativeCommand
-} from "../../index-eeqmg7qm.js";
+} from "../../index-6m6a9ty4.js";
 import"../../index-tgzhq07n.js";
 
 // src/agent-runtime/sandbox-bubblewrap.ts

package/dist/entrypoints/application/diagnostic-journal.js

@@ -14,9 +14,10 @@ import {
 import {
   createBoundedChannel2
 } from "../../index-w0eqdhyd.js";
+import"../../index-nybn2err.js";
 import {
   attemptExclusiveLock
-} from "../../index-7kxw1awn.js";
+} from "../../index-ga597cvy.js";
 import {
   isRecord
 } from "../../index-9jfdm5tg.js";

package/dist/entrypoints/files.js

@@ -9,9 +9,10 @@ import {
 import {
   AppError2
 } from "../index-n53mswt3.js";
+import"../index-nybn2err.js";
 import {
   attemptExclusiveLock
-} from "../index-7kxw1awn.js";
+} from "../index-ga597cvy.js";
 import {
   writeFileAtomic2,
   writeFileAtomicSync2
@@ -300,7 +301,10 @@ function pause(ms, signal) {
 async function withExclusiveLock(path, run, options = {}) {
   const label = options.label ?? path;
   const timeoutMs = nonNegative("timeoutMs", options.timeoutMs, DEFAULT_TIMEOUT_MS);
-  const ownerlessGraceMs = nonNegative("ownerlessGraceMs", options.ownerlessGraceMs, DEFAULT_OWNERLESS_GRACE_MS);
+  const ownerlessGraceMs = options.ownerlessGraceMs === null ? null : nonNegative("ownerlessGraceMs", options.ownerlessGraceMs, DEFAULT_OWNERLESS_GRACE_MS);
+  const mode = options.mode ?? 384;
+  if (!Number.isInteger(mode) || mode < 0 || mode > 511)
+    throw new RangeError("[stitchkit] withExclusiveLock: mode must be permission bits from 0000 to 0777");
   const { signal } = options;
   const deadline = performance.now() + timeoutMs;
   let delay = FIRST_RETRY_MS;
@@ -309,7 +313,7 @@ async function withExclusiveLock(path, run, options = {}) {
       throw new ExclusiveLockError("LOCK_ABORTED", label, null, `[stitchkit] waiting for the lock on "${label}" was cancelled`, { cause: signal.reason });
     }
     const attempt = await attemptExclusiveLock(path, {
-      mode: options.mode ?? 384,
+      mode,
       reclaim: true,
       ownerlessGraceMs,
       ...options.machineIdentity !== undefined && {
@@ -333,7 +337,7 @@ async function withExclusiveLock(path, run, options = {}) {
     const remaining = deadline - performance.now();
     if (remaining <= 0) {
       const holder = attempt.diagnosis?.owner ?? null;
-      throw new ExclusiveLockError("LOCK_TIMEOUT", label, holder, `[stitchkit] the lock on "${label}" is held by ${describeHolder(holder)}${describeEvidence(attempt.diagnosis)}; gave up after ${timeoutMs} ms`, { cause: attempt.error });
+      throw new ExclusiveLockError("LOCK_TIMEOUT", label, holder, `[stitchkit] the lock on "${label}" is held by ${describeHolder(holder)}${describeEvidence(attempt.diagnosis)}; gave up after ${timeoutMs} ms`, { cause: attempt.diagnosis?.cause ?? attempt.error });
     }
     await pause(Math.min(delay * (0.5 + Math.random() / 2), remaining), signal);
     delay = Math.min(delay * 2, MAX_RETRY_MS);

package/dist/entrypoints/process.d.ts

@@ -1,4 +1,5 @@
 /** POSIX Node/Bun finite native commands, independent of the agent runtime. */
+export { observeProcessInstance, type ProcessInstance, type ProcessInstanceObservation, ProcessInstanceSchema, type ProcessOwnerEvidence, probeProcessOwner, } from '../internal/process-instance.js';
 export { runNativeCommand } from '../process/command.js';
-export { NativeCommandError, type NativeCommandOptions, type NativeCommandResult, } from '../process/contract.js';
+export { NativeCommandError, type NativeCommandOptions, type NativeCommandResult, type NativeCommandSettlement, } from '../process/contract.js';
 //# sourceMappingURL=process.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC"}

package/dist/entrypoints/process.js

@@ -1,13 +1,20 @@
+import {
+  ProcessInstanceSchema2,
+  observeProcessInstance2,
+  probeProcessOwner2
+} from "../index-nybn2err.js";
 import {
   NativeCommandError2,
   startNativeCommand
-} from "../index-eeqmg7qm.js";
-
+} from "../index-6m6a9ty4.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;
 }
 export {
   NativeCommandError2 as NativeCommandError,
+  ProcessInstanceSchema2 as ProcessInstanceSchema,
+  observeProcessInstance2 as observeProcessInstance,
+  probeProcessOwner2 as probeProcessOwner,
   runNativeCommand
 };

package/dist/{index-eeqmg7qm.js → index-6m6a9ty4.js}

@@ -4,6 +4,14 @@ import {
 
 // src/process/contract.ts
 import { z } from "zod";
+var NativeCommandSettlementSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("exit"),
+    exitCode: z.number().int().nullable(),
+    signal: z.string().nullable()
+  }),
+  z.object({ kind: z.literal("error"), cause: z.unknown() })
+]);
 var NativeCommandOptionsSchema = z.strictObject({
   executable: z.string().min(1),
   args: z.array(z.string()).default([]),
@@ -17,6 +25,7 @@ var NativeCommandOptionsSchema = z.strictObject({
   stdin: z.custom((v) => v instanceof Uint8Array).optional(),
   maxStdinBytes: z.number().int().positive().default(1024 * 1024),
   onOutput: z.custom((v) => typeof v === "function").optional(),
+  onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
   killGraceMs: z.number().int().nonnegative().max(1e4).default(100),
   cleanupTimeoutMs: z.number().int().positive().max(30000).default(2000)
 }).superRefine((input, ctx) => {
@@ -50,6 +59,9 @@ class NativeCommandError2 extends Error {
 import { spawn } from "node:child_process";
 
 // src/process/group.ts
+function deniedOnDarwin(error) {
+  return process.platform === "darwin" && error instanceof Error && "code" in error && error.code === "EPERM";
+}
 function signalGroup(pid, signal) {
   if (pid === undefined)
     return;
@@ -69,15 +81,30 @@ function exists(pid) {
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ESRCH")
       return false;
+    if (deniedOnDarwin(error))
+      return true;
     throw error;
   }
 }
-async function stopCommandGroup(pid, graceMs) {
-  signalGroup(pid, "SIGTERM");
+async function signalUntilSettled(pid, signal, deadline) {
+  for (;; ) {
+    try {
+      signalGroup(pid, signal);
+      return;
+    } catch (error) {
+      if (!deniedOnDarwin(error) || Date.now() >= deadline)
+        throw error;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(10, deadline - Date.now())));
+    }
+  }
+}
+async function stopCommandGroup(pid, graceMs, cleanupTimeoutMs = 2000) {
+  const deadline = Date.now() + graceMs + cleanupTimeoutMs;
+  await signalUntilSettled(pid, "SIGTERM", deadline);
   const until = Date.now() + graceMs;
   while (Date.now() < until && exists(pid))
     await new Promise((resolve) => setTimeout(resolve, Math.min(10, until - Date.now())));
-  signalGroup(pid, "SIGKILL");
+  await signalUntilSettled(pid, "SIGKILL", deadline);
 }
 function commandCleanupError(cause) {
   return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
@@ -88,6 +115,39 @@ function waitForCommandClose(closed, timeoutMs) {
   return raceAbort(closed, AbortSignal.timeout(timeoutMs));
 }
 
+// src/process/leader-settlement.ts
+function createLeaderSettlement(options, signal) {
+  let pending;
+  return (event) => {
+    if (pending)
+      return pending;
+    pending = (async () => {
+      if (!options.onLeaderSettled)
+        return;
+      const controller = new AbortController;
+      const timer = setTimeout(() => controller.abort(new Error("Leader settlement deadline exceeded")), options.cleanupTimeoutMs);
+      const abort = () => controller.abort(signal.reason);
+      if (!signal.aborted)
+        signal.addEventListener("abort", abort, { once: true });
+      try {
+        await raceAbort(Promise.resolve(options.onLeaderSettled(event, controller.signal)), controller.signal);
+      } catch (cause) {
+        if (signal.aborted && cause === signal.reason)
+          throw cause;
+        throw commandCleanupError(new AggregateError([event, cause], "Leader settlement failed"));
+      } finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+        controller.abort(new Error("Leader settlement completed"));
+      }
+    })();
+    pending.catch(() => {
+      return;
+    });
+    return pending;
+  };
+}
+
 // src/process/command-owner.ts
 function startNativeCommand(input, onSpawn) {
   const options = NativeCommandOptionsSchema.parse(input);
@@ -119,6 +179,19 @@ function startNativeCommand(input, onSpawn) {
   let total = 0;
   let finished = false;
   let spawnFailure;
+  const settle = createLeaderSettlement(options, controller.signal);
+  const leader = new Promise((resolve) => {
+    child.once("exit", (exitCode, signal) => resolve({ kind: "exit", exitCode, signal }));
+    child.once("error", (cause) => resolve({ kind: "error", cause }));
+  });
+  const pendingHandles = new Set(["leader", "stdin", "stdout", "stderr"]);
+  const released = Promise.all([
+    leader.then(() => pendingHandles.delete("leader")),
+    ...["stdin", "stdout", "stderr"].map((name) => new Promise((resolve) => child[name].once("close", () => {
+      pendingHandles.delete(name);
+      resolve();
+    })))
+  ]);
   const closed = new Promise((resolve) => {
     child.once("error", (error) => {
       spawnFailure = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
@@ -157,7 +230,7 @@ function startNativeCommand(input, onSpawn) {
         drain(child.stdout, "stdout", stdout),
         drain(child.stderr, "stderr", stderr)
       ]);
-      await raceAbort(drains, controller.signal);
+      await raceAbort(Promise.all([drains, leader.then(settle)]), controller.signal);
       const status = await raceAbort(closed, controller.signal);
       if (spawnFailure !== undefined)
         throw spawnFailure;
@@ -167,11 +240,21 @@ function startNativeCommand(input, onSpawn) {
       child.stdin.destroy();
       child.stdout.destroy();
       child.stderr.destroy();
-      try {
-        await stopCommandGroup(child.pid, options.killGraceMs);
-        await waitForCommandClose(closed, options.cleanupTimeoutMs);
-      } catch (cleanup) {
-        throw commandCleanupError(new AggregateError([error, cleanup], "Command failed and cleanup failed"));
+      const cleanup = await Promise.allSettled([
+        settle({ kind: "error", cause: error }),
+        stopCommandGroup(child.pid, options.killGraceMs, options.cleanupTimeoutMs).then(async () => {
+          try {
+            await waitForCommandClose(released, options.cleanupTimeoutMs);
+          } catch (cause) {
+            throw new Error(`Command handles remained open: ${[...pendingHandles].join(", ")}`, {
+              cause
+            });
+          }
+        })
+      ]);
+      const failures = cleanup.flatMap((item) => item.status === "rejected" && item.reason !== error ? [item.reason] : []);
+      if (failures.length) {
+        throw commandCleanupError(new AggregateError([error, ...failures], "Command failed and cleanup failed"));
       }
       throw error;
     } finally {

package/dist/index-ga597cvy.js

@@ -0,0 +1,184 @@
+import {
+  machineIdentity,
+  ProcessInstanceSchema2,
+  readProcessInstance,
+  probeProcessOwner2
+} from "./index-nybn2err.js";
+import {
+  isRecord
+} from "./index-9jfdm5tg.js";
+
+// src/internal/exclusive-lock.ts
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+import { z } from "zod";
+var ExclusiveLockOwnerSchema = z.object({
+  pid: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  host: z.string().min(1),
+  acquiredAt: z.string(),
+  machine: z.string().min(1).optional().catch(undefined),
+  process: ProcessInstanceSchema2.nullable().optional().catch(null)
+});
+function isCode(error, code) {
+  return isRecord(error) && error.code === code;
+}
+function readOwner(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return;
+  }
+  const owner = ExclusiveLockOwnerSchema.safeParse(parsed);
+  return owner.success ? owner.data : undefined;
+}
+function attribute(owner, identity) {
+  if (identity !== null && owner.machine !== undefined) {
+    return owner.machine === identity ? "this-machine" : "another-machine";
+  }
+  return owner.host === hostname() ? "this-machine" : "unattributable";
+}
+async function diagnose(owner, declaredIdentity) {
+  if (!owner)
+    return { attribution: "unattributable", liveness: "not-probed", owner: null };
+  const attribution = attribute(owner, await machineIdentity(declaredIdentity));
+  if (attribution !== "this-machine")
+    return { attribution, liveness: "not-probed", owner };
+  return { attribution, ...await probeProcessOwner2(owner.pid, owner.process), owner };
+}
+async function readLockFile(path, onFailure) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    return {
+      owner: readOwner(await handle.readFile("utf8")),
+      ino: info.ino,
+      mtimeMs: info.mtimeMs
+    };
+  } catch (cause) {
+    if (!isCode(cause, "ENOENT"))
+      onFailure?.(cause);
+    return;
+  } finally {
+    await handle?.close().catch(() => {
+      return;
+    });
+  }
+}
+async function unlinkIfSame(path, ino) {
+  try {
+    if ((await lstat(path)).ino !== ino)
+      return;
+    await unlink(path);
+  } catch (error) {
+    if (!isCode(error, "ENOENT"))
+      throw error;
+  }
+}
+async function createOwned(path, options, reclaimed) {
+  const identity = await machineIdentity(options.machineIdentity);
+  const instance = await readProcessInstance(process.pid);
+  const handle = await open(path, "wx", options.mode);
+  const owner = {
+    pid: process.pid,
+    process: instance,
+    host: hostname(),
+    acquiredAt: new Date().toISOString(),
+    ...identity !== null && { machine: identity }
+  };
+  let ino;
+  try {
+    ino = (await handle.stat()).ino;
+    await handle.chmod(options.mode);
+    await handle.writeFile(`${JSON.stringify(owner)}
+`, "utf8");
+  } catch (error) {
+    await handle.close().catch(() => {
+      return;
+    });
+    if (ino !== undefined)
+      await unlinkIfSame(path, ino).catch(() => {
+        return;
+      });
+    throw error;
+  }
+  const ownedInode = ino;
+  let released = false;
+  return {
+    path,
+    owner,
+    reclaimed,
+    async release() {
+      if (released)
+        return;
+      released = true;
+      try {
+        await handle.close();
+      } finally {
+        await unlinkIfSame(path, ownedInode);
+      }
+    }
+  };
+}
+function reclaimable(state, diagnosis, graceMs) {
+  if (state.owner)
+    return diagnosis.liveness === "gone";
+  return typeof graceMs === "number" && Date.now() - state.mtimeMs >= graceMs;
+}
+async function reclaimUnderGuard(path, options) {
+  const guardPath = `${path}.reclaim`;
+  const acquired = await attemptExclusiveLock(guardPath, {
+    ...options,
+    ownerlessGraceMs: options.ownerlessGraceMs === undefined ? 5000 : options.ownerlessGraceMs
+  });
+  if (!("held" in acquired))
+    return;
+  const guard = acquired.held;
+  try {
+    const state = await readLockFile(path);
+    if (state) {
+      const diagnosis = await diagnose(state.owner, options.machineIdentity);
+      if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
+        return "refused";
+      await unlinkIfSame(path, state.ino);
+    }
+    return await createOwned(path, options, state !== undefined).catch((error) => {
+      if (isCode(error, "EEXIST"))
+        return "refused";
+      throw error;
+    });
+  } finally {
+    await guard.release().catch(() => {
+      return;
+    });
+  }
+}
+async function attemptExclusiveLock(path, options) {
+  try {
+    return { held: await createOwned(path, options, false) };
+  } catch (error) {
+    if (!isCode(error, "EEXIST"))
+      throw error;
+    if (!options.reclaim)
+      return { error };
+    let readFailure;
+    const state = await readLockFile(path, (cause) => {
+      readFailure = cause;
+    });
+    const diagnosis = {
+      ...await diagnose(state?.owner, options.machineIdentity),
+      ...readFailure !== undefined && { cause: readFailure }
+    };
+    if (!state || !reclaimable(state, diagnosis, options.ownerlessGraceMs)) {
+      return { error, diagnosis };
+    }
+    const reclaimed = await reclaimUnderGuard(path, options);
+    if (reclaimed !== undefined && reclaimed !== "refused")
+      return { held: reclaimed };
+    return { error, diagnosis };
+  }
+}
+
+export { attemptExclusiveLock };