stitchkit 0.108.0 → 0.108.2

package/dist/{index-4q9jvqg7.js → index-k0kzhdw9.js}

@@ -70,6 +70,7 @@ var NativeCommandOptionsSchema = z.strictObject({
   onLeaderStarted: z.custom((v) => typeof v === "function").optional(),
   drainTimeoutMs: z.number().int().positive().max(MAX_TIMER_MS).optional(),
   group: z.enum(["own", "caller"]).default("own"),
+  ownerLoss: z.enum(["terminate"]).optional(),
   stdio: z.enum(["pipe", "inherit"]).default("pipe"),
   stop: NativeCommandStopPolicySchema.optional(),
   descendants: z.enum(["terminate-after-leader", "leave"]).optional(),
@@ -108,6 +109,12 @@ var NativeCommandOptionsSchema = z.strictObject({
       input: ctx.value,
       message: "group: 'caller' has no group of its own, so descendants does not apply"
     });
+  if (input.group === "caller" && input.ownerLoss !== undefined)
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      message: "ownerLoss: 'terminate' requires group: 'own'"
+    });
   if (input.stdio === "inherit") {
     const piped = [
       input.capture && "capture",
@@ -395,20 +402,371 @@ function createCommandLifetime(input) {
 }
 
 // src/process/launch.ts
-import { Readable as Readable2 } from "node:stream";
+import { Readable as Readable3 } from "node:stream";
 
 // src/process/owned-child.ts
 import { spawn } from "node:child_process";
+import { Duplex } from "node:stream";
+
+// src/process/bun-child.ts
+import { EventEmitter } from "node:events";
+import { Readable, Writable } from "node:stream";
+
+// src/process/owner-loss-control.ts
+import { z as z2 } from "zod";
+var MAX_GUARD_MESSAGE_BYTES = 4096;
+var OwnerLossGuardMessageSchema = z2.discriminatedUnion("kind", [
+  z2.strictObject({ kind: z2.literal("started"), pid: z2.number().int().positive() }),
+  z2.strictObject({
+    kind: z2.literal("unavailable"),
+    message: z2.string().min(1).max(1024),
+    code: z2.string().min(1).max(64).optional()
+  })
+]);
+var guards = new WeakMap;
+function abortOwnerLossLaunch(pid) {
+  if (pid === undefined)
+    return;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch (error) {
+    if (!(error instanceof Error && ("code" in error) && error.code === "ESRCH"))
+      throw error;
+  }
+}
+function unavailable(message, cause) {
+  return new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
+    cause: cause ?? new Error(message)
+  });
+}
+function attachOwnerLossControl(child, control) {
+  const settled = Promise.withResolvers();
+  settled.promise.catch(() => {
+    return;
+  });
+  let complete = false;
+  let bytes = 0;
+  let text = "";
+  const decoder = new TextDecoder;
+  const ignoreSettledError = () => {
+    return;
+  };
+  const finish = (outcome) => {
+    if (complete)
+      return;
+    complete = true;
+    control.off("data", onData);
+    control.off("end", onMissing);
+    control.off("close", onMissing);
+    control.off("error", onError);
+    control.on("error", ignoreSettledError);
+    control.once("close", () => control.off("error", ignoreSettledError));
+    if ("pid" in outcome)
+      settled.resolve(outcome.pid);
+    else
+      settled.reject(outcome.error);
+  };
+  const onMissing = () => finish({ error: unavailable("Owner-loss guard exited before the command started") });
+  const onError = (cause) => finish({ error: unavailable("Owner-loss guard control failed", cause) });
+  const onData = (chunk) => {
+    if (complete)
+      return;
+    bytes += chunk.byteLength;
+    if (bytes > MAX_GUARD_MESSAGE_BYTES) {
+      finish({ error: unavailable("Owner-loss guard response exceeded its finite bound") });
+      return;
+    }
+    text += decoder.decode(chunk, { stream: true });
+    const newline = text.indexOf(`
+`);
+    if (newline < 0)
+      return;
+    try {
+      const message = OwnerLossGuardMessageSchema.parse(JSON.parse(text.slice(0, newline)));
+      if (message.kind === "started")
+        finish({ pid: message.pid });
+      else {
+        const cause = new Error(message.message);
+        if (message.code !== undefined)
+          Object.defineProperty(cause, "code", { value: message.code });
+        finish({ error: unavailable(message.message, cause) });
+      }
+    } catch (cause) {
+      finish({ error: unavailable("Owner-loss guard returned an invalid response", cause) });
+    }
+  };
+  control.on("data", onData);
+  control.once("end", onMissing);
+  control.once("close", onMissing);
+  control.once("error", onError);
+  child.on("exit", onMissing);
+  guards.set(child, { control, started: settled.promise });
+}
+function transferOwnerLossControl(source, target) {
+  const registration = guards.get(source);
+  if (registration !== undefined)
+    guards.set(target, registration);
+}
+async function awaitCommandStart(child) {
+  const registration = guards.get(child);
+  if (registration !== undefined)
+    await registration.started;
+  return child.pid;
+}
+
+// src/process/owner-loss-protocol.ts
+var OWNER_LOSS_GUARD_FLAG = "--stitchkit-owner-loss-guard-v1";
+function ownerLossAvailable(platform) {
+  return platform === "linux" || platform === "darwin";
+}
+function ownerLossGuardCommand(guard, executable, args) {
+  return [
+    process.execPath,
+    guard.entry,
+    OWNER_LOSS_GUARD_FLAG,
+    guard.signalTarget,
+    executable,
+    ...args
+  ];
+}
+
+// src/process/owner-loss-socket.ts
+import { connect } from "node:net";
+function connectOwnerLossSocket(fd) {
+  return Reflect.apply(connect, undefined, [{ fd }]);
+}
+
+// src/process/bun-child.ts
+function hostIsBun() {
+  return typeof Bun !== "undefined";
+}
+function readableOf(source) {
+  const reader = source.getReader();
+  let reading = false;
+  return new Readable({
+    read() {
+      if (reading)
+        return;
+      reading = true;
+      reader.read().then(({ done, value }) => {
+        reading = false;
+        if (done)
+          this.push(null);
+        else
+          this.push(value);
+      }, (error) => {
+        reading = false;
+        this.destroy(error instanceof Error ? error : new Error(String(error)));
+      });
+    },
+    destroy(error, done) {
+      reader.cancel().then(() => done(error), () => done(error));
+    }
+  });
+}
+var REPORTED_SPAWN_CODES = new Set(["ENOENT", "EACCES", "EAGAIN", "EMFILE", "ENFILE"]);
+function reportedSpawnFailure(cause) {
+  return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" && REPORTED_SPAWN_CODES.has(cause.code);
+}
+var waitClosed = (stream) => stream.closed ? Promise.resolve() : new Promise((resolve) => stream.once("close", () => resolve()));
+function defineBunChildren() {
+
+  class BunProcess extends EventEmitter {
+    pipes;
+    pid;
+    exitCode = null;
+    signalCode = null;
+    #subprocess;
+    constructor(pipes) {
+      super();
+      this.pipes = pipes;
+    }
+    watch(subprocess) {
+      this.pid = subprocess.pid;
+      this.#subprocess = subprocess;
+      subprocess.exited.then(() => {
+        this.exitCode = subprocess.exitCode;
+        this.signalCode = subprocess.signalCode;
+        this.emit("exit", this.exitCode, this.signalCode);
+        for (const pipe of this.pipes)
+          if (pipe.readableFlowing === null)
+            pipe.resume();
+        this.closeAfterPipes();
+      });
+    }
+    fail(cause) {
+      for (const pipe of this.pipes)
+        pipe.resume();
+      setImmediate(() => {
+        this.emit("error", cause);
+        this.closeAfterPipes();
+      });
+    }
+    kill(signal) {
+      const subprocess = this.#subprocess;
+      if (!subprocess || this.exitCode !== null || this.signalCode !== null)
+        return false;
+      try {
+        subprocess.kill(signal);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    closeAfterPipes() {
+      Promise.all(this.pipes.map(waitClosed)).then(() => this.emit("close", this.exitCode, this.signalCode));
+    }
+  }
+
+  class BunChild extends BunProcess {
+    stdin;
+    stdout;
+    stderr;
+    constructor(stdin, stdout, stderr) {
+      super([stdout, stderr]);
+      this.stdin = stdin;
+      this.stdout = stdout;
+      this.stderr = stderr;
+    }
+  }
+  return { BunProcess, BunChild };
+}
+var bunChildren;
+function children() {
+  bunChildren ??= defineBunChildren();
+  return bunChildren;
+}
+function sinkWritable(sink) {
+  let ended = false;
+  const end = () => {
+    if (ended)
+      return Promise.resolve(0);
+    ended = true;
+    return Promise.resolve().then(() => sink.end());
+  };
+  return new Writable({
+    write(chunk, _encoding, done) {
+      Promise.resolve().then(() => sink.write(chunk)).then(() => done(), done);
+    },
+    final(done) {
+      end().then(() => done(), done);
+    },
+    destroy(error, done) {
+      end().then(() => done(error), () => done(error));
+    }
+  });
+}
+function spawnBunChild(input) {
+  const { BunChild } = children();
+  try {
+    const ownerLoss = input.ownerLoss;
+    const guarded = ownerLoss !== undefined;
+    const command = guarded ? ownerLossGuardCommand(ownerLoss, input.executable, input.args) : [input.executable, ...input.args];
+    const subprocess = guarded ? Bun.spawn(command, {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdio: ["pipe", "pipe", "pipe", "socket-fd"]
+    }) : Bun.spawn(command, {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const child = new BunChild(sinkWritable(subprocess.stdin), readableOf(subprocess.stdout), readableOf(subprocess.stderr));
+    child.watch(subprocess);
+    if (guarded) {
+      const fd = subprocess.stdio[3];
+      if (typeof fd !== "number") {
+        abortOwnerLossLaunch(subprocess.pid);
+        throw new Error("Owner-loss guard supplied no control socket");
+      }
+      attachOwnerLossControl(child, connectOwnerLossSocket(fd));
+    }
+    return child;
+  } catch (cause) {
+    if (!reportedSpawnFailure(cause))
+      throw cause;
+    const child = new BunChild(new Writable({ write: (_chunk, _encoding, done) => done() }), Readable.from([]), Readable.from([]));
+    child.fail(cause);
+    return child;
+  }
+}
+function spawnBunInheritedChild(input) {
+  const { BunProcess } = children();
+  const child = new BunProcess([]);
+  try {
+    const ownerLoss = input.ownerLoss;
+    const guarded = ownerLoss !== undefined;
+    const command = guarded ? ownerLossGuardCommand(ownerLoss, input.executable, input.args) : [input.executable, ...input.args];
+    const subprocess = guarded ? Bun.spawn(command, {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdio: ["inherit", "inherit", "inherit", "socket-fd"]
+    }) : Bun.spawn(command, {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit"
+    });
+    child.watch(subprocess);
+    if (guarded) {
+      const fd = subprocess.stdio[3];
+      if (typeof fd !== "number") {
+        abortOwnerLossLaunch(subprocess.pid);
+        throw new Error("Owner-loss guard supplied no control socket");
+      }
+      attachOwnerLossControl(child, connectOwnerLossSocket(fd));
+    }
+  } catch (cause) {
+    if (!reportedSpawnFailure(cause))
+      throw cause;
+    child.fail(cause);
+  }
+  return child;
+}
+function spawnBunGuardTarget(executable, args) {
+  return Bun.spawn([executable, ...args], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit"
+  });
+}
+
+// src/process/owned-child.ts
 var groups = new WeakSet;
 function spawnOwnedCommand(input) {
-  const child = spawn(input.executable, [...input.args], {
+  const child = hostIsBun() ? spawnBunChild(input) : nodeChild(input);
+  if (input.group)
+    groups.add(child);
+  return child;
+}
+function nodeChild(input) {
+  if (input.ownerLoss === undefined)
+    return spawn(input.executable, [...input.args], {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  const [executable, ...args] = ownerLossGuardCommand(input.ownerLoss, input.executable, input.args);
+  const child = spawn(executable, args, {
     cwd: input.cwd,
     env: input.env,
     detached: input.group,
-    stdio: ["pipe", "pipe", "pipe"]
+    stdio: ["pipe", "pipe", "pipe", "pipe"]
   });
-  if (input.group)
-    groups.add(child);
+  const control = child.stdio[3];
+  if (!(control instanceof Duplex)) {
+    abortOwnerLossLaunch(child.pid);
+    throw new Error("Owner-loss guard supplied no control pipe");
+  }
+  attachOwnerLossControl(child, control);
   return child;
 }
 var INHERITED_OUTPUT = {
@@ -445,12 +803,31 @@ class InheritedChild {
   }
 }
 function spawnInheritedCommand(input) {
-  const child = new InheritedChild(spawn(input.executable, [...input.args], {
-    cwd: input.cwd,
-    env: input.env,
-    detached: input.group,
-    stdio: "inherit"
-  }));
+  const observable = hostIsBun() ? spawnBunInheritedChild(input) : (() => {
+    if (input.ownerLoss === undefined)
+      return spawn(input.executable, [...input.args], {
+        cwd: input.cwd,
+        env: input.env,
+        detached: input.group,
+        stdio: "inherit"
+      });
+    const [executable, ...args] = ownerLossGuardCommand(input.ownerLoss, input.executable, input.args);
+    const spawned = spawn(executable, args, {
+      cwd: input.cwd,
+      env: input.env,
+      detached: input.group,
+      stdio: ["inherit", "inherit", "inherit", "pipe"]
+    });
+    const control = spawned.stdio[3];
+    if (!(control instanceof Duplex)) {
+      abortOwnerLossLaunch(spawned.pid);
+      throw new Error("Owner-loss guard supplied no control pipe");
+    }
+    attachOwnerLossControl(spawned, control);
+    return spawned;
+  })();
+  const child = new InheritedChild(observable);
+  transferOwnerLossControl(observable, child);
   if (input.group)
     groups.add(child);
   return child;
@@ -459,8 +836,153 @@ function ownsCommandGroup(child) {
   return groups.has(child);
 }
 
+// src/process/owner-loss-guard.ts
+import { spawn as spawn2 } from "node:child_process";
+import { Socket } from "node:net";
+import { fileURLToPath } from "node:url";
+var FORWARDED_SIGNALS = [
+  "SIGTERM",
+  "SIGINT",
+  "SIGHUP",
+  "SIGQUIT",
+  "SIGUSR1",
+  "SIGUSR2"
+];
+function causeMessage(cause) {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  if (typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string")
+    return { message, code: cause.code };
+  return { message };
+}
+function guardMessage(control, message, written) {
+  control.write(`${JSON.stringify(message)}
+`, written);
+}
+function mirrorTargetExit(control, code, signal) {
+  control.destroy();
+  if (signal !== null)
+    process.kill(process.pid, signal);
+  else
+    process.exitCode = code ?? 1;
+}
+function refuseTarget(control, cause) {
+  const detail = causeMessage(cause);
+  control.end(`${JSON.stringify({ kind: "unavailable", ...detail })}
+`, () => {
+    process.exitCode = 127;
+  });
+}
+function spawnNodeTarget(executable, args, onStarted, onExit, onUnavailable) {
+  let child;
+  try {
+    child = spawn2(executable, [...args], { stdio: "inherit" });
+  } catch (cause) {
+    onUnavailable(cause);
+    return;
+  }
+  child.once("spawn", () => {
+    const pid = child.pid;
+    if (pid === undefined)
+      onUnavailable(new Error("Command started without a pid"));
+    else
+      onStarted(pid);
+  });
+  child.once("error", onUnavailable);
+  child.once("exit", onExit);
+}
+function spawnBunTarget(executable, args, onStarted, onExit, onUnavailable) {
+  let child;
+  try {
+    child = spawnBunGuardTarget(executable, args);
+  } catch (cause) {
+    onUnavailable(cause);
+    return;
+  }
+  onStarted(child.pid);
+  child.exited.then(() => onExit(child.exitCode, child.signalCode));
+}
+function runOwnerLossGuard(signalTarget, executable, args) {
+  const bun = hostIsBun();
+  const control = bun ? connectOwnerLossSocket(3) : new Socket({ fd: 3, readable: true, writable: true });
+  let armed = true;
+  const ownerLost = () => {
+    if (!armed)
+      return;
+    process.kill(-process.pid, "SIGKILL");
+  };
+  control.once("end", ownerLost);
+  control.once("close", ownerLost);
+  control.once("error", ownerLost);
+  if (signalTarget !== "group" && signalTarget !== "leader" || executable === undefined) {
+    armed = false;
+    refuseTarget(control, new Error("Owner-loss guard received an invalid invocation"));
+    return;
+  }
+  let targetPid;
+  let handshakeWritten = false;
+  let pendingTargetExit;
+  const forwarders = new Map;
+  if (signalTarget === "leader")
+    for (const signal of FORWARDED_SIGNALS) {
+      const forward = () => {
+        if (targetPid === undefined)
+          return;
+        try {
+          process.kill(targetPid, signal);
+        } catch (error) {
+          if (!(error instanceof Error && ("code" in error) && error.code === "ESRCH"))
+            throw error;
+        }
+      };
+      forwarders.set(signal, forward);
+      process.on(signal, forward);
+    }
+  const removeForwarders = () => {
+    for (const [signal, forward] of forwarders)
+      process.removeListener(signal, forward);
+    forwarders.clear();
+  };
+  const targetStarted = (pid) => {
+    targetPid = pid;
+    guardMessage(control, { kind: "started", pid }, () => {
+      handshakeWritten = true;
+      const pending = pendingTargetExit;
+      if (pending !== undefined) {
+        pendingTargetExit = undefined;
+        targetExit(pending.code, pending.signal);
+      }
+    });
+  };
+  const targetExit = (code, signal) => {
+    if (!handshakeWritten) {
+      pendingTargetExit = { code, signal };
+      return;
+    }
+    armed = false;
+    removeForwarders();
+    mirrorTargetExit(control, code, signal);
+  };
+  const targetUnavailable = (cause) => {
+    armed = false;
+    removeForwarders();
+    refuseTarget(control, cause);
+  };
+  if (!bun)
+    spawnNodeTarget(executable, args, targetStarted, targetExit, targetUnavailable);
+  else
+    spawnBunTarget(executable, args, targetStarted, targetExit, targetUnavailable);
+}
+function ownerLossGuardEntry() {
+  return fileURLToPath(import.meta.url);
+}
+if (process.argv[2] === OWNER_LOSS_GUARD_FLAG) {
+  const entry = process.argv[1];
+  if (entry !== undefined && fileURLToPath(import.meta.url) === entry)
+    runOwnerLossGuard(process.argv[3], process.argv[4], process.argv.slice(5));
+}
+
 // src/process/transport.ts
-import { Readable, Writable } from "node:stream";
+import { Readable as Readable2, Writable as Writable2 } from "node:stream";
 function createCommandTransport(child) {
   const leader = Promise.withResolvers();
   const closed = Promise.withResolvers();
@@ -517,17 +1039,17 @@ function createCommandTransport(child) {
       stderr = child.stderr;
       destructors.set("stderr", () => stderr?.destroy());
       const input = "stdin" in child ? child.stdin : undefined;
-      if (input instanceof Writable) {
+      if (input instanceof Writable2) {
         stdin = input;
         pendingHandles.add("stdin");
         destructors.set("stdin", () => input.destroy());
         pipe("stdin", input);
       }
-      if (stdout instanceof Readable)
+      if (stdout instanceof Readable2)
         pipe("stdout", stdout);
-      if (stderr instanceof Readable)
+      if (stderr instanceof Readable2)
         pipe("stderr", stderr);
-      if (stdout instanceof Readable && stderr instanceof Readable)
+      if (stdout instanceof Readable2 && stderr instanceof Readable2)
         release("launcher");
       return { stdout, stderr };
     },
@@ -545,7 +1067,7 @@ function createCommandTransport(child) {
             child.stdout.destroy();
           else if (name === "stderr")
             child.stderr.destroy();
-          else if ("stdin" in child && child.stdin instanceof Writable)
+          else if ("stdin" in child && child.stdin instanceof Writable2)
             child.stdin.destroy();
         } catch (cause) {
           failures.push(cause);
@@ -578,7 +1100,7 @@ function nativeCommandOwner(child) {
   return owners.get(child);
 }
 function outputStream(source, closed, maxBufferedBytes) {
-  if (source instanceof Readable2)
+  if (source instanceof Readable3)
     return {
       bytes: source,
       destroy() {
@@ -661,7 +1183,8 @@ function launchNativeCommand({
     args: options.args,
     cwd: options.cwd,
     env: options.envPolicy === "ambient" ? { ...process.env, ...options.env } : options.env ?? {},
-    group: options.group === "own" && (driver?.group ?? true)
+    group: options.group === "own" && (driver?.group ?? true),
+    ownerLoss: options.ownerLoss === "terminate" ? { entry: ownerLossGuardEntry(), signalTarget: options.stop.target } : undefined
   };
   let inherited;
   if (!launch) {
@@ -690,10 +1213,12 @@ function launchNativeCommand({
     ...transport,
     stdout: stdout.bytes,
     stderr: stderr.bytes,
-    start() {
+    async start() {
       if (native)
         onSpawn?.(native);
+      const pid = await awaitCommandStart(child);
       stdin?.end(options.stdin);
+      return pid;
     }
   };
 }
@@ -852,6 +1377,10 @@ function startNativeCommand(input, onSpawn, driver) {
   killOn?.throwIfAborted();
   if (process.platform === "win32" && driver?.group !== false)
     throw new NativeCommandError2("COMMAND_UNAVAILABLE", "POSIX process groups are required");
+  if (options.ownerLoss === "terminate" && !ownerLossAvailable(process.platform))
+    throw new NativeCommandError2("COMMAND_UNAVAILABLE", "ownerLoss: 'terminate' is available on Linux and Darwin");
+  if (options.ownerLoss === "terminate" && (driver?.launch !== undefined || driver?.group === false))
+    throw new NativeCommandError2("COMMAND_UNAVAILABLE", "ownerLoss: 'terminate' requires the package-owned process-group launcher");
   const { cleanupTimeoutMs, timeoutMs } = nativeCommandBudgets(options, driver);
   const controller = new AbortController;
   const abort = () => controller.abort(options.signal?.reason);
@@ -957,8 +1486,7 @@ function startNativeCommand(input, onSpawn, driver) {
   };
   const run = (async () => {
     try {
-      launched.start();
-      const pid = acquired?.child.pid;
+      const pid = await raceAbort(launched.start(), controller.signal);
       if (pid !== undefined)
         options.onLeaderStarted?.({ pid });
       const drains = Promise.all([

package/dist/{index-dwf0gymy.js → index-vyaehh67.js}

@@ -5,7 +5,7 @@ import {
   NativeCommandError2,
   CommandStopped,
   startNativeCommand
-} from "./index-4q9jvqg7.js";
+} from "./index-k0kzhdw9.js";
 import {
   probeAgentProcessSandboxOutcome,
   missingSandboxRestrictions2,