stitchkit 0.103.9 → 0.103.11

package/dist/index-ttf0y7b8.js

@@ -0,0 +1,246 @@
+import {
+  machineIdentity,
+  ProcessInstanceSchema2,
+  readProcessInstance,
+  probeProcessOwner2
+} from "./index-nybn2err.js";
+import {
+  isRecord
+} from "./index-9jfdm5tg.js";
+
+// src/internal/exclusive-lock.ts
+import { lstat, open as open2, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+import { z } from "zod";
+
+// src/internal/exclusive-lock-read.ts
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+var OWNER_RECORD_BYTES = 16 * 1024;
+
+class LockRecordError extends Error {
+  code;
+  name = "LockRecordError";
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+async function readLockRecord(path, openDescriptor = open, signal) {
+  signal?.throwIfAborted();
+  if (!constants.O_NOFOLLOW || !constants.O_NONBLOCK) {
+    throw new LockRecordError("LOCK_UNSAFE_RECORD", "Safe lock descriptor flags are unavailable");
+  }
+  const handle = await openDescriptor(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    signal?.throwIfAborted();
+    const before = await handle.stat();
+    signal?.throwIfAborted();
+    if (!before.isFile() || before.nlink !== 1) {
+      throw new LockRecordError("LOCK_UNSAFE_RECORD", "Lock record must be a regular file with one link");
+    }
+    if (before.size > OWNER_RECORD_BYTES) {
+      throw new LockRecordError("LOCK_RECORD_TOO_LARGE", "Lock owner record exceeds its byte cap");
+    }
+    const bytes = Buffer.alloc(OWNER_RECORD_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      signal?.throwIfAborted();
+      const read = await handle.read(bytes, length, bytes.length - length, length);
+      if (read.bytesRead === 0)
+        break;
+      length += read.bytesRead;
+    }
+    if (length > OWNER_RECORD_BYTES) {
+      throw new LockRecordError("LOCK_RECORD_TOO_LARGE", "Lock owner record grew beyond its byte cap");
+    }
+    const after = await handle.stat();
+    signal?.throwIfAborted();
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.nlink !== after.nlink || length !== after.size) {
+      throw new LockRecordError("LOCK_RECORD_CHANGED", "Lock owner record changed during its read");
+    }
+    return { text: bytes.subarray(0, length).toString("utf8"), info: after };
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/internal/exclusive-lock.ts
+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, signal) {
+  try {
+    const record = await readLockRecord(path, undefined, signal);
+    return {
+      owner: readOwner(record.text),
+      ino: record.info.ino,
+      dev: record.info.dev,
+      mtimeMs: record.info.mtimeMs
+    };
+  } catch (cause) {
+    if (!isCode(cause, "ENOENT"))
+      onFailure?.(cause);
+    return;
+  }
+}
+async function unlinkIfSame(path, ino, dev) {
+  try {
+    const current = await lstat(path);
+    if (current.ino !== ino || current.dev !== dev || !current.isFile() || current.nlink !== 1)
+      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 open2(path, "wx", options.mode);
+  const owner = {
+    pid: process.pid,
+    process: instance,
+    host: hostname(),
+    acquiredAt: new Date().toISOString(),
+    ...identity !== null && { machine: identity }
+  };
+  let ino;
+  let dev;
+  try {
+    const info = await handle.stat();
+    ino = info.ino;
+    dev = info.dev;
+    await handle.chmod(options.mode);
+    await handle.writeFile(`${JSON.stringify(owner)}
+`, "utf8");
+  } catch (error) {
+    await handle.close().catch(() => {
+      return;
+    });
+    if (ino !== undefined && dev !== undefined)
+      await unlinkIfSame(path, ino, dev).catch(() => {
+        return;
+      });
+    throw error;
+  }
+  const ownedInode = ino;
+  const ownedDevice = dev;
+  let released = false;
+  return {
+    path,
+    owner,
+    reclaimed,
+    async release() {
+      if (released)
+        return;
+      released = true;
+      try {
+        await handle.close();
+      } finally {
+        await unlinkIfSame(path, ownedInode, ownedDevice);
+      }
+    }
+  };
+}
+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 {
+    let unsafe = false;
+    const state = await readLockFile(path, () => {
+      unsafe = true;
+    }, options.signal);
+    if (unsafe)
+      return "refused";
+    if (state) {
+      const diagnosis = await diagnose(state.owner, options.machineIdentity);
+      if (options.signal?.aborted)
+        return "refused";
+      if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
+        return "refused";
+      await unlinkIfSame(path, state.ino, state.dev);
+    }
+    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;
+    }, options.signal);
+    const diagnosis = {
+      ...await diagnose(state?.owner, options.machineIdentity),
+      ...readFailure !== undefined && { cause: readFailure }
+    };
+    if (options.signal?.aborted)
+      return { error, diagnosis };
+    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 };

package/dist/internal/exclusive-lock-read.d.ts

@@ -0,0 +1,20 @@
+import { type Stats } from 'node:fs';
+interface LockRecordDescriptor {
+    stat(): Promise<Stats>;
+    read(buffer: Buffer, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    close(): Promise<void>;
+}
+export declare class LockRecordError extends Error {
+    readonly code: 'LOCK_UNSAFE_RECORD' | 'LOCK_RECORD_CHANGED' | 'LOCK_RECORD_TOO_LARGE';
+    name: string;
+    constructor(code: 'LOCK_UNSAFE_RECORD' | 'LOCK_RECORD_CHANGED' | 'LOCK_RECORD_TOO_LARGE', message: string);
+}
+/** A descriptor-bound observation, never a pathname stat followed by an unbounded read. */
+export declare function readLockRecord(path: string, openDescriptor?: (path: string, flags: number) => Promise<LockRecordDescriptor>, signal?: AbortSignal): Promise<{
+    text: string;
+    info: Stats;
+}>;
+export {};
+//# sourceMappingURL=exclusive-lock-read.d.ts.map

package/dist/internal/exclusive-lock-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusive-lock-read.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAMhD,UAAU,oBAAoB;IAC5B,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,IAAI,CACF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB;IAF9E,IAAI,SAAqB;IAClC,YACW,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB,EACrF,OAAO,EAAE,MAAM,EAGhB;CACF;AAED,2FAA2F;AAC3F,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,cAAc,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAQ,EACrF,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CA8DxC"}

package/dist/internal/exclusive-lock.d.ts

@@ -23,6 +23,7 @@ export interface ExclusiveLockDiagnosis {
     readonly liveness: 'alive' | 'gone' | 'not-probed';
     readonly identity?: ProcessOwnerEvidence['identity'];
     readonly owner: ExclusiveLockOwner | null;
+    readonly cause?: unknown;
 }
 /** A lock this process holds. */
 export interface HeldExclusiveLock {
@@ -34,6 +35,7 @@ export interface HeldExclusiveLock {
     release(): Promise<void>;
 }
 export interface ExclusiveLockAttemptOptions {
+    readonly signal?: AbortSignal;
     readonly mode: number;
     /** Take a lock whose owner is provably gone. `false` refuses every present lock. */
     readonly reclaim: boolean;
@@ -42,7 +44,7 @@ export interface ExclusiveLockAttemptOptions {
      * How old a lock with no readable owner must be before it is taken. Absent,
      * an ownerless lock is never taken — it may predate owner records.
      */
-    readonly ownerlessGraceMs?: number;
+    readonly ownerlessGraceMs?: number | null;
 }
 export type ExclusiveLockAttempt = {
     readonly held: HeldExclusiveLock;

package/dist/internal/exclusive-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAK5B,gDAAgD;AAChD,QAAA,MAAM,wBAAwB;;;;;;;;;;;;;;iBAO5B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC3C;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAmLN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}
+{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAG5B,gDAAgD;AAChD,QAAA,MAAM,wBAAwB;;;;;;;;;;;;;;iBAO5B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAkMN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CA0B/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}

package/dist/internal/process-instance.d.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { probeLiveness } from './process-identity.js';
 export declare const ProcessInstanceSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         darwin: "darwin";
@@ -10,17 +9,55 @@ export declare const ProcessInstanceSchema: z.ZodObject<{
     startId: z.ZodString;
 }, z.core.$strict>;
 export type ProcessInstance = z.infer<typeof ProcessInstanceSchema>;
+/** An unavailable observation preserves its native or validation cause; it never proves death. */
+declare const ProcessInstanceObservationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"observed">;
+    instance: z.ZodObject<{
+        platform: z.ZodEnum<{
+            darwin: "darwin";
+            linux: "linux";
+        }>;
+        bootId: z.ZodString;
+        namespace: z.ZodString;
+        startId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+    cause: z.ZodUnknown;
+}, z.core.$strip>], "state">;
+export type ProcessInstanceObservation = z.infer<typeof ProcessInstanceObservationSchema>;
+export declare function observeProcessInstance(pid: number): Promise<ProcessInstanceObservation>;
 /** /proc stat field 22 follows a command name that may itself contain spaces and parentheses. */
 export declare function linuxProcessStart(stat: string, pid: number): string | null;
 /** @internal procRoot permits kernel-format fixtures without changing a real process or boot. */
 export declare function readProcessInstance(pid: number, procRoot?: string): Promise<ProcessInstance | null>;
-export interface ProcessOwnerEvidence {
-    readonly liveness: 'alive' | 'gone' | 'not-probed';
-    readonly identity: 'matched' | 'different-boot' | 'reused-pid' | 'pid-gone' | 'legacy' | 'unavailable';
-}
+/** @internal The fixture root is never a public owner option. */
+export declare function observeProcessInstanceAt(pid: number, procRoot: string): Promise<ProcessInstanceObservation>;
+declare const ProcessOwnerEvidenceSchema: z.ZodObject<{
+    liveness: z.ZodEnum<{
+        alive: "alive";
+        gone: "gone";
+        "not-probed": "not-probed";
+    }>;
+    identity: z.ZodEnum<{
+        "different-boot": "different-boot";
+        legacy: "legacy";
+        matched: "matched";
+        "pid-gone": "pid-gone";
+        "reused-pid": "reused-pid";
+        unavailable: "unavailable";
+    }>;
+    cause: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type ProcessOwnerEvidence = z.infer<typeof ProcessOwnerEvidenceSchema>;
 /** Compare identities only inside one machine (the caller establishes that boundary). */
-export declare function probeProcessOwner(pid: number, recorded: ProcessInstance | null | undefined, probes?: {
-    read: typeof readProcessInstance;
-    liveness: typeof probeLiveness;
-}): Promise<ProcessOwnerEvidence>;
+export declare function probeProcessOwner(pid: number, recorded: ProcessInstance | null | undefined): Promise<ProcessOwnerEvidence>;
+interface ProcessOwnerProbes {
+    read(pid: number): Promise<ProcessInstance | null>;
+    liveness(pid: number): Promise<'alive' | 'gone'>;
+    observe?(pid: number): Promise<ProcessInstanceObservation>;
+}
+/** @internal Injection is for kernel-format controls, not a public ownership assertion. */
+export declare function probeProcessOwnerWith(pid: number, recorded: ProcessInstance | null | undefined, probes?: ProcessOwnerProbes): Promise<ProcessOwnerEvidence>;
+export {};
 //# sourceMappingURL=process-instance.d.ts.map

package/dist/internal/process-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-instance.d.ts","sourceRoot":"","sources":["../../src/internal/process-instance.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,eAAO,MAAM,qBAAqB;;;;;;;;kBAOvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1E;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,SAAU,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA6CjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,EACb,SAAS,GACT,gBAAgB,GAChB,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,aAAa,CAAC;CACnB;AAED,yFAAyF;AACzF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM;IAAK,IAAI;IAAuB,QAAQ;CAAiB,GAC9D,OAAO,CAAC,oBAAoB,CAAC,CAyB/B"}
+{"version":3,"file":"process-instance.d.ts","sourceRoot":"","sources":["../../src/internal/process-instance.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,qBAAqB;;;;;;;;kBAOvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,kGAAkG;AAClG,QAAA,MAAM,gCAAgC;;;;;;;;;;;;;;4BAGpC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,0BAA0B,CAAC,CAGrC;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1E;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,SAAU,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAGjC;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,0BAA0B,CAAC,CAsDrC;AAED,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,yFAAyF;AACzF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,UAAU,kBAAkB;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC5D;AAED,2FAA2F;AAC3F,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM,GAAE,kBAA2E,GAClF,OAAO,CAAC,oBAAoB,CAAC,CA2C/B"}

package/dist/internal/with-exclusive-lock.d.ts

@@ -18,7 +18,7 @@ export interface ExclusiveLockOptions {
     timeoutMs?: number;
     /** Stops the wait; an abort while waiting rejects at once with its reason as the cause. */
     signal?: AbortSignal;
-    /** Permission bits of the lock file. Default `0o600`. */
+    /** Exact permission bits, independent of umask. Default `0o600`. Shared readers need a common group and traversable parents. */
     mode?: number;
     /**
      * This machine's identity, for a platform that offers none (`/etc/machine-id`
@@ -29,9 +29,10 @@ export interface ExclusiveLockOptions {
     /**
      * How old a lock with no readable owner must be before it is taken — the one
      * case where time decides, left by a process that died between creating the
-     * file and recording itself. Default 5 000.
+     * file and recording itself. Default 5 000; `null` disables age-based reclaim,
+     * including abandoned ownerless reclaim guards.
      */
-    ownerlessGraceMs?: number;
+    ownerlessGraceMs?: number | null;
 }
 /** The lock `run` executes under. */
 export interface ExclusiveLock {

package/dist/internal/with-exclusive-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/with-exclusive-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IALnC,IAAI,SAAwB;IACrC,YACW,IAAI,EAAE,cAAc,GAAG,cAAc,EACrC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IAC/E,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG9B;CACF;AAyCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC,CAwDZ"}
+{"version":3,"file":"with-exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/with-exclusive-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gIAAgI;IAChI,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IALnC,IAAI,SAAwB;IACrC,YACW,IAAI,EAAE,cAAc,GAAG,cAAc,EACrC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IAC/E,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG9B;CACF;AAyCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC,CAuEZ"}

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

@@ -1,13 +1,18 @@
-import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import { type NativeCommandOptions } from './contract.js';
+import { type NativeCommandLaunchDriver } from './launch.js';
 /** One-shot native execution; sandbox policy/admission is composed above this owner. */
-export declare function startNativeCommand(input: NativeCommandOptions, onSpawn?: (child: ChildProcessWithoutNullStreams) => void): {
+export declare function startNativeCommand(input: NativeCommandOptions, onSpawn?: (child: ChildProcessWithoutNullStreams) => void, driver?: NativeCommandLaunchDriver): {
+    result: Promise<never>;
+    stop(): Promise<void>;
+} | {
     result: Promise<{
         exitCode: number | null;
         signal: string | null;
         stdout: Uint8Array<ArrayBuffer>;
         stderr: Uint8Array<ArrayBuffer>;
     }>;
+    terminate(): Promise<void>;
     stop(): Promise<void>;
 };
 //# sourceMappingURL=command-owner.d.ts.map

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,EAAE,KAAK,8BAA8B,EAAS,MAAM,oBAAoB,CAAC;AAGhF,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,YAAY,CAAC;AAGpB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI;;;;;;;;EA0H1D"}
+{"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;AAEzE,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,YAAY,CAAC;AAOpB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAIlB,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,EACzD,MAAM,CAAC,EAAE,yBAAyB;;;;;;;;;;;;EA+LnC"}

package/dist/process/contract.d.ts

@@ -1,4 +1,13 @@
 import { z } from 'zod';
+declare const NativeCommandSettlementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"exit">;
+    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">;
+export type NativeCommandSettlement = z.infer<typeof NativeCommandSettlementSchema>;
 export declare const NativeCommandOptionsSchema: z.ZodObject<{
     executable: z.ZodString;
     args: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -15,6 +24,7 @@ export declare const NativeCommandOptionsSchema: z.ZodObject<{
     stdin: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>>;
     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>>>;
     killGraceMs: z.ZodDefault<z.ZodNumber>;
     cleanupTimeoutMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
@@ -27,9 +37,20 @@ declare const NativeCommandResultSchema: z.ZodObject<{
     stderr: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
 }, z.core.$strip>;
 export type NativeCommandResult = z.infer<typeof NativeCommandResultSchema>;
+declare const NativeCommandLimitReasonSchema: z.ZodEnum<{
+    deadline: "deadline";
+    "output-budget": "output-budget";
+}>;
 export declare class NativeCommandError extends Error {
     readonly code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP';
-    constructor(code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP', message: string, options?: ErrorOptions);
+    /** Observed owner limit; absent on non-limit and caller-constructed errors without evidence. */
+    readonly reason: z.infer<typeof NativeCommandLimitReasonSchema> | undefined;
+    constructor(code: 'COMMAND_LIMIT', message: string, options?: ErrorOptions & {
+        reason?: z.infer<typeof NativeCommandLimitReasonSchema>;
+    });
+    constructor(code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP', message: string, options?: ErrorOptions & {
+        reason?: never;
+    });
 }
 export {};
 //# sourceMappingURL=contract.d.ts.map

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;AAExB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAoBtB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;;;kBAgB7B,CAAC;AACL,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,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IADnF,YACkB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjF,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,6BAA6B;;;;;;;2BAOjC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,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;;;kBAiBvF,CAAC;AACL,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,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,8BAA8B;;;EAAwC,CAAC;AAE7E,qBAAa,kBAAmB,SAAQ,KAAK;aAezB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IAdnF,gGAAgG;IAChG,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;CAeH"}

package/dist/process/group.d.ts

@@ -1,6 +1,11 @@
 import { NativeCommandError } from './contract.js';
+/** Chain native-sized timers; internal callers retain their declared safe-integer deadline. */
+export declare function createCommandDeadline(timeoutMs: number, reason: unknown): {
+    signal: AbortSignal;
+    cancel(): void;
+};
 export declare function signalGroup(pid: number | undefined, signal: NodeJS.Signals): void;
-export declare function stopCommandGroup(pid: number | undefined, graceMs: number): Promise<void>;
+export declare function stopCommandGroup(pid: number | undefined, graceMs: number, cleanupTimeoutMs?: number, force?: boolean): Promise<void>;
 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":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAOjF;AAYD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAQf;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,CAExF"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAapE,MAAM;IACN,MAAM;EAIT;AAWD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAOjF;AAiCD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,MAAM,EACf,gBAAgB,SAAO,EACvB,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC,CAaf;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

@@ -0,0 +1,65 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type ParsedNativeCommandOptions } from './contract.js';
+/** A structural host launcher may supply pipes without importing Node ambient types. */
+export interface NativeCommandLaunchedProcess {
+    readonly pid?: number;
+    readonly exitCode: number | null;
+    readonly signalCode: string | null;
+    readonly stdout: NativeCommandLaunchedOutput;
+    readonly stderr: NativeCommandLaunchedOutput;
+    kill(signal: 'SIGKILL'): boolean;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit' | 'close', listener: (code: number | null, signal: string | null) => void): unknown;
+}
+interface NativeCommandLaunchedOutput {
+    readonly destroyed: boolean;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    destroy(): unknown;
+}
+/** Internal transport selection; application policy never enters the public command contract. */
+export interface NativeCommandLaunchDriver {
+    launch?: () => NativeCommandLaunchedProcess;
+    maxBufferedBytes?: number;
+    group?: boolean;
+    force?: boolean;
+    cleanupTimeoutMs?: number;
+    timeoutMs?: number;
+    closeTimeoutMs?: number;
+}
+/** Driver overrides retain the same finite, safe-integer budget admission. */
+export declare function nativeCommandBudgets(options: ParsedNativeCommandOptions, driver: NativeCommandLaunchDriver | undefined): {
+    cleanupTimeoutMs: number;
+    timeoutMs: number | undefined;
+};
+interface NativeCommandOwner {
+    result: Promise<unknown>;
+    stop(): Promise<void>;
+    terminate(): Promise<void>;
+}
+/** A launcher and its admission owner share the execution owner's shutdown barrier. */
+export declare function registerNativeCommandOwner(child: object, owner: NativeCommandOwner): void;
+export declare function nativeCommandOwner(child: object): NativeCommandOwner | undefined;
+/** Install every observation before starting stdin or invoking an admission callback. */
+export declare function launchNativeCommand(options: ParsedNativeCommandOptions, driver: NativeCommandLaunchDriver | undefined, onSpawn: ((child: ChildProcessWithoutNullStreams) => void) | undefined, onFailure: (error: Error) => void, onInputFailure: (error: Error) => void): {
+    child: NativeCommandLaunchedProcess;
+    stdout: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    stderr: AsyncIterable<Uint8Array<ArrayBufferLike>>;
+    leader: Promise<{
+        kind: "exit";
+        exitCode: number | null;
+        signal: string | null;
+    } | {
+        kind: "error";
+        cause: unknown;
+    }>;
+    closed: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    released: Promise<[boolean, ...boolean[]]>;
+    pendingHandles: Set<string>;
+    start(): void;
+    destroy(): void;
+};
+export {};
+//# sourceMappingURL=launch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/process/launch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,8BAA8B,EAAS,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,YAAY,CAAC;AAEpB,wFAAwF;AACxF,MAAM,WAAW,4BAA4B;IAC3C,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;IACnC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC9D,EAAE,CACA,KAAK,EAAE,MAAM,GAAG,OAAO,EACvB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAC7D,OAAO,CAAC;CACZ;AAED,UAAU,2BAA2B;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC;CACpB;AAED,iGAAiG;AACjG,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,4BAA4B,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,yBAAyB,GAAG,SAAS;;;EAY9C;AAED,UAAU,kBAAkB;IAC1B,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAGD,uFAAuF;AACvF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAEzF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEhF;AA4ED,yFAAyF;AACzF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,CAAC,GAAG,SAAS,EACtE,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EACjC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;;;;;;;;;;;;;kBAuBC,MAAM,GAAG,IAAI;gBAAU,MAAM,GAAG,IAAI;;;;;;EA0D5E"}

package/dist/process/leader-settlement.d.ts

@@ -0,0 +1,6 @@
+import type { NativeCommandSettlement, ParsedNativeCommandOptions } from './contract.js';
+/** An internal caller may bound drain/close after leader settlement without changing generic drain. */
+export declare function createLeaderCloseDeadline(leader: Promise<NativeCommandSettlement>, timeoutMs: number | undefined, controller: AbortController): () => void;
+/** One bounded external resource settlement, shared by observed exit and terminal failure. */
+export declare function createLeaderSettlement(options: ParsedNativeCommandOptions, signal: AbortSignal): (event: NativeCommandSettlement) => Promise<void>;
+//# sourceMappingURL=leader-settlement.d.ts.map

package/dist/process/leader-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-settlement.d.ts","sourceRoot":"","sources":["../../src/process/leader-settlement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAGtF,uGAAuG;AACvG,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,CAAC,uBAAuB,CAAC,EACxC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,eAAe,cAmB5B;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,WAAW,WAGJ,uBAAuB,KAAG,OAAO,CAAC,IAAI,CAAC,CAmCvD"}

package/dist/process/start-failure.d.ts

@@ -0,0 +1,7 @@
+import { type NativeCommandSettlement } from './contract.js';
+/** A failed native admission still owns one bounded external-resource settlement. */
+export declare function failedCommandStart(cause: unknown, settle: (event: NativeCommandSettlement) => Promise<void>): {
+    result: Promise<never>;
+    stop(): Promise<void>;
+};
+//# sourceMappingURL=start-failure.d.ts.map

package/dist/process/start-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-failure.d.ts","sourceRoot":"","sources":["../../src/process/start-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG9E,qFAAqF;AACrF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC;;;EAyB1D"}

package/llms/agent-runtime.txt

@@ -19,7 +19,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-09-28 18:39 +07:00
+updated: 2026-10-02 16:28 +07:00
 ---
 
 # Agent application runtime
@@ -376,6 +376,12 @@ second host executable, so Windows kills the direct child, destroys retained pip
 deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
 `cancelled` without spawning.
 
+Coding commands compose the shared native execution owner. Artifact retention and UTF-8
+previews remain coding-tool policy; normal leader exit still forcibly stops remaining POSIX
+group members before draining. A structural sandbox launcher uses the same settlement owner
+with a finite output queue. Sandbox shutdown waits for actual owned completion and surfaces
+cleanup refusal rather than treating it as successful teardown.
+
 One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
 concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
 new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;