@humwick/server 0.130.1 → 0.130.2

package/node_modules/@humwick/offload/src/async-runner.ts

@@ -1,170 +0,0 @@
-import PQueue from "p-queue";
-import { beginRun, finishLog, recordResult, startLog, type RunContext } from "./envelope.js";
-import { OffloadError, StrikeCounter, normalizeError, validateTimeout, type OffloadDefaults, type OffloadEnvelope } from "./types.js";
-
-export interface AsyncRunnerOptions extends OffloadDefaults {
-  concurrency: number;
-}
-
-export interface AsyncRunner {
-  run<T>(taskName: string, fn: (signal: AbortSignal) => Promise<T> | T, env?: OffloadEnvelope): Promise<T>;
-  readonly stats: { active: number; queued: number };
-  /** Resolves when everything accepted so far has finished. Does not cancel anything. */
-  drain(): Promise<void>;
-  /** Cancels in-flight work, settles every outstanding caller, and refuses new work. */
-  destroy(): Promise<void>;
-}
-
-type Outcome<T> = { ok: true; value: T } | { ok: false; error: OffloadError };
-
-type LiveRun = {
-  taskName: string;
-  teardown: AbortController;
-  settled: Promise<void>;
-  /** Settles a caller whose work has not started yet; a no-op once it has. */
-  cancelIfQueued(error: OffloadError): void;
-};
-
-/** Bounded I/O runner. Work receives the composed signal and must cooperate with aborts. */
-export function createAsyncRunner(options: AsyncRunnerOptions): AsyncRunner {
-  if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1) throw new RangeError("concurrency must be a positive integer");
-  const queue = new PQueue({ concurrency: options.concurrency });
-  const counter = new StrikeCounter(options.escalationThreshold, options.escalationWindowAttempts);
-  const live = new Set<LiveRun>();
-  let destroyed = false;
-
-  const abortedError = (taskName: string, cause?: unknown): OffloadError =>
-    new OffloadError({ kind: "aborted", taskName, message: `${taskName} was aborted`, cause });
-  const destroyedError = (taskName: string): OffloadError =>
-    new OffloadError({ kind: "aborted", taskName, message: `${taskName} was cancelled: async runner destroyed` });
-
-  return {
-    get stats() { return { active: queue.pending, queued: queue.size }; },
-    async run<T>(taskName: string, fn: (signal: AbortSignal) => Promise<T> | T, env?: OffloadEnvelope): Promise<T> {
-      const labels = env?.labels ?? {};
-      const logger = env?.logger ?? options.logger;
-      const sink = env?.onEscalate ?? options.onEscalate;
-      const reportRejection = async (error: OffloadError): Promise<never> => {
-        // Rejecting before the run reaches startLog is still a terminal outcome; without this
-        // the structured stream shows nothing at all for it.
-        finishLog(logger, "async", taskName, labels, performance.now(), error);
-        await recordResult({ counter, taskName, backend: "async", labels, error, sink, logger });
-        throw error;
-      };
-      if (destroyed) return reportRejection(destroyedError(taskName));
-      if (env?.signal?.aborted) return reportRejection(abortedError(taskName, env.signal.reason));
-      // Eagerly validated so an invalid deadline rejects with an OffloadError rather than
-      // escaping the queue callback as a raw RangeError (#1809 P0-1, same class).
-      try {
-        validateTimeout(env?.timeoutMs ?? options.defaultTimeoutMs);
-      } catch (error) {
-        return reportRejection(normalizeError(taskName, error, "rejected"));
-      }
-
-      let publish!: (outcome: Outcome<T>) => void;
-      let published = false;
-      const outcome = new Promise<Outcome<T>>((resolve) => {
-        publish = (value) => { if (!published) { published = true; resolve(value); } };
-      });
-      let started = false;
-      let cancelled = false;
-      const entry: LiveRun = {
-        taskName,
-        teardown: new AbortController(),
-        settled: outcome.then(() => undefined),
-        cancelIfQueued: (error) => {
-          if (started || cancelled) return;
-          cancelled = true;
-          // The single funnel for both abort-while-queued and destroy()-cancels-queued, so
-          // the one line each terminal path owes the structured stream is emitted here. The
-          // callback bails on `cancelled` without logging, which keeps it to exactly one.
-          finishLog(logger, "async", taskName, labels, performance.now(), error);
-          publish({ ok: false, error });
-        },
-      };
-      live.add(entry);
-
-      // p-queue's own `signal` option used to provide this, but it also released the slot
-      // while the work kept running (#1809 P1-7). Cancelling here keeps abort prompt for
-      // queued work without lying about occupancy.
-      const signal = env?.signal;
-      const onQueuedAbort = signal ? () => entry.cancelIfQueued(abortedError(taskName, signal.reason)) : undefined;
-      if (signal && onQueuedAbort) signal.addEventListener("abort", onQueuedAbort, { once: true });
-
-      const task = queue.add(async () => {
-        if (signal && onQueuedAbort) signal.removeEventListener("abort", onQueuedAbort);
-        let work: Promise<T> | undefined;
-        let context: RunContext | undefined;
-        let onAbort: (() => void) | undefined;
-        try {
-          if (cancelled) return;
-          if (destroyed || entry.teardown.signal.aborted) {
-            const error = destroyedError(taskName);
-            finishLog(logger, "async", taskName, labels, performance.now(), error);
-            publish({ ok: false, error });
-            return;
-          }
-          started = true;
-          // Match WorkerPool semantics: a task's deadline starts when it receives a slot,
-          // not while it is waiting behind unrelated bounded work.
-          context = beginRun(taskName, env, options, entry.teardown.signal);
-          const run = context;
-          const startedAt = startLog(logger, "async", taskName, labels);
-          try {
-            if (run.signal.aborted) throw run.abortError();
-            const abort = new Promise<never>((_, reject) => {
-              onAbort = () => reject(run.abortError());
-              run.signal.addEventListener("abort", onAbort, { once: true });
-            });
-            work = Promise.resolve().then(() => fn(run.signal));
-            const value = await Promise.race([work, abort]);
-            finishLog(logger, "async", taskName, labels, startedAt);
-            await recordResult({ counter, taskName, backend: "async", labels, sink, logger });
-            publish({ ok: true, value });
-          } catch (error) {
-            const normalized = run.signal.aborted ? run.abortError() : normalizeError(taskName, error);
-            finishLog(logger, "async", taskName, labels, startedAt, normalized);
-            await recordResult({ counter, taskName, backend: "async", labels, error: normalized, sink, logger });
-            publish({ ok: false, error: normalized });
-          } finally {
-            // The composite signal stays reachable from the caller's long-lived signal, so an
-            // un-removed listener retains this closure for the process lifetime (#1809 P0-4).
-            if (onAbort) run.signal.removeEventListener("abort", onAbort);
-            run.cleanup();
-          }
-        } catch (error) {
-          const normalized = normalizeError(taskName, error, "rejected");
-          finishLog(logger, "async", taskName, labels, performance.now(), normalized);
-          await recordResult({ counter, taskName, backend: "async", labels, error: normalized, sink, logger });
-          publish({ ok: false, error: normalized });
-        } finally {
-          context?.cleanup();
-          // The caller may already have been settled by the abort race; the slot stays held
-          // until the work itself finishes, otherwise the cap admits a replacement while the
-          // aborted task is still running and `stats` under-reports it (#1809 P1-7).
-          if (work) await work.catch(() => undefined);
-          live.delete(entry);
-        }
-      });
-      // The callback settles callers through `publish` and never throws, but a stray
-      // rejection here would surface as an unhandled rejection rather than a failed run.
-      void task.catch(() => undefined);
-
-      const result = await outcome;
-      if (!result.ok) throw result.error;
-      return result.value;
-    },
-    drain: () => queue.onIdle(),
-    async destroy(): Promise<void> {
-      destroyed = true;
-      const outstanding = [...live];
-      for (const entry of outstanding) {
-        entry.cancelIfQueued(destroyedError(entry.taskName));
-        entry.teardown.abort(new DOMException("Async runner destroyed", "AbortError"));
-      }
-      // Waits on caller settlement rather than `queue.onIdle()`: work that ignores its signal
-      // must not be able to make teardown hang. Its slot is still held until it finishes.
-      await Promise.all(outstanding.map((entry) => entry.settled));
-    },
-  };
-}

package/node_modules/@humwick/offload/src/envelope.ts

@@ -1,92 +0,0 @@
-import { OffloadError, type OffloadDefaults, type OffloadEnvelope, type OffloadLogger, type EscalationEvent, type EscalationSink, type StrikeCounter, log, validateTimeout } from "./types.js";
-
-export interface RunContext {
-  signal: AbortSignal;
-  timeoutMs?: number;
-  cleanup(): void;
-  abortError(): OffloadError;
-}
-
-/**
- * `teardown` is the backend's own cancellation channel (runner `destroy()`); it is composed
- * with the caller's signal and the deadline so every backend has exactly one signal to observe.
- */
-export function beginRun(taskName: string, env: OffloadEnvelope | undefined, defaults: OffloadDefaults, teardown?: AbortSignal, timeoutMsOverride?: number | null): RunContext {
-  // `timeoutMsOverride` lets the WorkerPool pass an ALREADY-RESOLVED timeout: a number (e.g. the
-  // remaining budget of an absolute deadline on a retry-safe re-dispatch, #1822 MED-2) or `null`
-  // meaning "no deadline, definitively." Either way it is authoritative and already validated, so
-  // the envelope AND the mutable pool default are NOT re-read — that is what keeps a post-submission
-  // mutation of either from adding or erasing this job's deadline (#1822 MED). `null` is used for
-  // "no deadline" rather than `undefined` on purpose: `undefined` is indistinguishable from "no
-  // argument passed", which is how the async/subprocess runners ask to resolve from env/default.
-  const timeoutMs = timeoutMsOverride === undefined
-    ? validateTimeout(env?.timeoutMs ?? defaults.defaultTimeoutMs)
-    : (timeoutMsOverride ?? undefined);
-  const timeout = new AbortController();
-  const sources = [env?.signal, teardown].filter((source): source is AbortSignal => source !== undefined);
-  const signal = sources.length === 0 ? timeout.signal : AbortSignal.any([...sources, timeout.signal]);
-  let timedOut = false;
-  const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
-    timedOut = true;
-    timeout.abort(new DOMException(`Timed out after ${timeoutMs}ms`, "TimeoutError"));
-  }, timeoutMs);
-  return {
-    signal,
-    timeoutMs,
-    cleanup: () => { if (timer) clearTimeout(timer); },
-    abortError: () => new OffloadError({
-      kind: timedOut ? "timeout" : "aborted",
-      taskName,
-      message: timedOut ? `${taskName} timed out after ${timeoutMs}ms` : `${taskName} was aborted`,
-      cause: signal.reason,
-    }),
-  };
-}
-
-// Labels are spread FIRST throughout: adopters pass generic context bags, and a label that
-// happens to be named `taskName` or `backend` must not silently replace the envelope's own
-// fields — that would destroy exactly the uniformity this logging contract exists to provide.
-export function startLog(logger: OffloadLogger | undefined, backend: EscalationEvent["backend"], taskName: string, labels: Record<string, string>): number {
-  const startedAt = performance.now();
-  log(logger, "debug", "offload started", { ...labels, backend, taskName });
-  return startedAt;
-}
-
-export function finishLog(logger: OffloadLogger | undefined, backend: EscalationEvent["backend"], taskName: string, labels: Record<string, string>, startedAt: number, error?: OffloadError): void {
-  const fields = { ...labels, backend, taskName, tookMs: Math.round(performance.now() - startedAt) };
-  if (error) log(logger, "warn", "offload failed", { ...fields, kind: error.kind, code: error.code, error: error.message });
-  else log(logger, "debug", "offload completed", fields);
-}
-
-export async function recordResult(options: {
-  counter: StrikeCounter;
-  taskName: string;
-  backend: EscalationEvent["backend"];
-  labels: Record<string, string>;
-  error?: OffloadError;
-  sink?: EscalationSink;
-  logger?: OffloadLogger;
-}): Promise<void> {
-  if (!options.error) {
-    options.counter.succeed(options.taskName);
-    return;
-  }
-  // Caller-directed cancellation is neither a backend failure nor a timeout. It must not
-  // page a host merely because a legitimate shutdown cancelled several queued operations.
-  if (options.error.kind === "aborted") return;
-  const strikes = options.counter.fail(options.taskName);
-  if (strikes < options.counter.threshold) return;
-  // Like the maintenance breaker, escalation is edge-triggered: one notification at
-  // the threshold, then a latch until a successful run re-arms the task.
-  options.counter.trip(options.taskName);
-  if (!options.sink) return;
-  try {
-    await options.sink({ taskName: options.taskName, backend: options.backend, error: options.error, strikes, labels: options.labels });
-  } catch (error) {
-    log(options.logger, "error", "offload escalation sink failed", { taskName: options.taskName, backend: options.backend, error: String(error) });
-  }
-}
-
-export function errorForExit(taskName: string, code?: string): OffloadError {
-  return new OffloadError({ kind: "worker-exit", taskName, code, message: `${taskName} worker exited${code ? ` (${code})` : ""}` });
-}

package/node_modules/@humwick/offload/src/fixtures/worker-task.ts

@@ -1,49 +0,0 @@
-import { appendFileSync, readFileSync } from "node:fs";
-import type { OffloadWorkerTask } from "../worker.js";
-
-// `file`-based counters let a test count executions/deaths deterministically across worker
-// threads (a shared in-process counter is not visible from a worker), so the #1822 F2/F3 tests
-// can PROVE the mechanism (exactly-once, bounded retries, real deaths) instead of hoping on
-// timing. Each execution/death appends one byte; the test reads the file size.
-const task: OffloadWorkerTask<{ kind: string; ms?: number; value?: unknown; file?: string; code?: number }, unknown> = async (input) => {
-  if (input.kind === "burn") {
-    const until = Date.now() + (input.ms ?? 0);
-    while (Date.now() < until) { /* intentionally synchronous: timeout must terminate this worker */ }
-    return input.value ?? "burned";
-  }
-  if (input.kind === "delay") {
-    await Bun.sleep(input.ms ?? 0);
-    return input.value;
-  }
-  if (input.kind === "throw") throw Object.assign(new RangeError("bad worker input"), { code: "BAD_INPUT" });
-  if (input.kind === "exit") process.exit(1);
-  // Returns a value now, then exits AFTER the slot has gone idle: simulates an OOM/SIGKILL
-  // that lands on a worker between jobs, which is the #1822 item 2 scenario. Records the death
-  // to `file` (if given) so a test can assert the deaths actually happened.
-  if (input.kind === "exit-when-idle") {
-    setTimeout(() => { if (input.file) appendFileSync(input.file, "d"); process.exit(0); }, input.ms ?? 20);
-    return input.value ?? "ok";
-  }
-  // Optionally runs for `ms` (so a deadline can bite mid-execution), records one execution to
-  // `file`, then exits the worker every time. Exits with `code` (default 1 = abnormal); pass
-  // code 0 to model a CLEAN worker exit while a job is in flight. Used to prove at-most-once
-  // (default → one record) vs bounded retry (retrySafe → MAX+1 records), the absolute deadline,
-  // and exit-manner attribution (abnormal charges, clean does not — #1822 MED-4).
-  if (input.kind === "crash-record") {
-    if (input.ms) await Bun.sleep(input.ms);
-    if (input.file) appendFileSync(input.file, "x");
-    process.exit(input.code ?? 1);
-  }
-  // Records one execution, then crashes ONLY on the first execution (file was empty) and succeeds
-  // on any retry — proves a retry-safe re-dispatch recovers and is bounded (file has 2 records).
-  if (input.kind === "flaky-record") {
-    let prior = 0;
-    try { prior = input.file ? readFileSync(input.file, "utf8").length : 0; } catch { prior = 0; }
-    if (input.file) appendFileSync(input.file, "x");
-    if (prior === 0) process.exit(1);
-    return input.value ?? "recovered";
-  }
-  return input.value;
-};
-
-export default task;

package/node_modules/@humwick/offload/src/index.ts

@@ -1,4 +0,0 @@
-export { createAsyncRunner, type AsyncRunner, type AsyncRunnerOptions } from "./async-runner.js";
-export { createSubprocessRunner, type SubprocessResult, type SubprocessRunner, type SubprocessRunnerOptions, type SubprocessSpec } from "./subprocess-runner.js";
-export { createWorkerPool, type WorkerPool, type WorkerPoolOptions, type WorkerPoolStats } from "./worker-pool.js";
-export { OffloadError, StrikeCounter, type EscalationEvent, type EscalationSink, type OffloadDefaults, type OffloadEnvelope, type OffloadErrorKind, type OffloadLogger } from "./types.js";

package/node_modules/@humwick/offload/src/subprocess-runner.ts

@@ -1,334 +0,0 @@
-import PQueue from "p-queue";
-import { beginRun, finishLog, recordResult, startLog, type RunContext } from "./envelope.js";
-import { OffloadError, StrikeCounter, normalizeError, validateTimeout, type OffloadDefaults, type OffloadEnvelope } from "./types.js";
-
-export interface SubprocessSpec {
-  command: string[];
-  cwd?: string;
-  env?: Record<string, string | undefined>;
-  /**
-   * Exit codes that are a normal ANSWER rather than a failure. Defaults to `[0]`; pass
-   * `"any"` when every code is data (a land gate whose failing codes are not enumerable).
-   *
-   * Probe-shaped callers use a non-zero exit as data — `tmux has-session` exits 1 when the
-   * session is absent, `git rev-parse` exits 128 outside a repo, `which` exits 1. Without
-   * this they reject AND take an escalation strike for a healthy result, which inverts the
-   * signal: the sink pages on a healthy fleet, then latches (it only re-arms on a success,
-   * which never comes in that steady state) so the real outage is silent.
-   *
-   * `"any"` includes SIGNAL DEATHS — a child killed by SIGKILL (137) or SIGSEGV (139)
-   * returns as a success and RE-ARMS the strike counter. That is intended for a land gate,
-   * where an OOM-killed gate is simply a failed gate, but it means an infrastructure death
-   * reads as a healthy answer and will never escalate. Prefer an explicit code list unless
-   * the failing codes genuinely cannot be enumerated. Timeout and abort still throw.
-   */
-  okExitCodes?: readonly number[] | "any";
-}
-
-export interface SubprocessResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-  /** True when either stream hit `maxOutputBytes` and the captured text was cut short. */
-  truncated: boolean;
-}
-
-export interface SubprocessRunnerOptions extends OffloadDefaults {
-  concurrency?: number;
-  /**
-   * How long a child may keep running after SIGTERM before it is SIGKILLed. This is the
-   * slack on the deadline: a run cannot outlive `timeoutMs + killGraceMs` (plus a short
-   * reap window) even if it traps or ignores SIGTERM. Defaults to 2000ms.
-   */
-  killGraceMs?: number;
-  /** Captured bytes per stream before output is truncated. Defaults to 8 MiB. */
-  maxOutputBytes?: number;
-}
-
-export interface SubprocessRunner {
-  run(taskName: string, process: SubprocessSpec, env?: OffloadEnvelope): Promise<SubprocessResult>;
-  readonly stats: { active: number; queued: number };
-  /** A subprocess owns the heavy work, so maintenance callers may mark their await window off-thread. */
-  readonly offThread: true;
-  /** Resolves when everything accepted so far has finished. Does not cancel anything. */
-  drain(): Promise<void>;
-  /** SIGKILLs and awaits every live child, settles every outstanding caller, and refuses new work. */
-  destroy(): Promise<void>;
-}
-
-type Child = ReturnType<typeof Bun.spawn>;
-
-const DEFAULT_KILL_GRACE_MS = 2_000;
-const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
-/** How long to wait for a SIGKILLed child to be reaped before giving its slot back anyway. */
-const REAP_GRACE_MS = 1_000;
-
-/**
- * `detached` children are reparented rather than reaped when the host dies (#1809 P1-5), so
- * every live group is killed from a single process-level exit hook. One module-scoped hook
- * keeps runner instances from piling up `exit` listeners.
- */
-const liveChildren = new Set<Child>();
-let exitHookInstalled = false;
-
-function killGroup(child: Child, signal: NodeJS.Signals): void {
-  try {
-    if (process.platform !== "win32") process.kill(-child.pid, signal);
-    else child.kill();
-  } catch {
-    try { child.kill(signal); } catch { /* the child is already gone */ }
-  }
-}
-
-function trackChild(child: Child): void {
-  liveChildren.add(child);
-  if (exitHookInstalled) return;
-  exitHookInstalled = true;
-  process.on("exit", () => {
-    for (const live of liveChildren) killGroup(live, "SIGKILL");
-  });
-}
-
-/** Reads a stream up to `limit` bytes, then keeps draining so the child never blocks on a full pipe. */
-async function readCapped(stream: ReadableStream<Uint8Array> | null, limit: number): Promise<{ text: string; truncated: boolean }> {
-  if (!stream) return { text: "", truncated: false };
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let size = 0;
-  let truncated = false;
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (!value) continue;
-      const remaining = limit - size;
-      if (remaining <= 0) {
-        truncated = true;
-        continue;
-      }
-      if (value.byteLength > remaining) {
-        chunks.push(value.subarray(0, remaining));
-        size = limit;
-        truncated = true;
-        continue;
-      }
-      chunks.push(value);
-      size += value.byteLength;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  const buffer = new Uint8Array(size);
-  let offset = 0;
-  for (const chunk of chunks) {
-    buffer.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return { text: new TextDecoder().decode(buffer), truncated };
-}
-
-type Outcome = { ok: true; value: SubprocessResult } | { ok: false; error: OffloadError };
-
-type LiveRun = {
-  taskName: string;
-  teardown: AbortController;
-  settled: Promise<void>;
-  /** Settles a caller whose child has not been spawned yet; a no-op once it has. */
-  cancelIfQueued(error: OffloadError): void;
-};
-
-/**
- * Bounded wrapper around the repo's standard `Bun.spawn(... { stdout: "pipe", stderr: "pipe" })`
- * pattern. On POSIX, each run gets its own process group so timeout/abort also kills
- * descendants (for example shell, git, or install subprocess trees); Windows falls back
- * to Bun's direct-child kill because POSIX process groups do not exist there.
- */
-export function createSubprocessRunner(options: SubprocessRunnerOptions = {}): SubprocessRunner {
-  const queue = new PQueue({ concurrency: options.concurrency ?? 1 });
-  const counter = new StrikeCounter(options.escalationThreshold, options.escalationWindowAttempts);
-  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
-  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
-  if (!Number.isFinite(killGraceMs) || killGraceMs < 0) throw new RangeError("killGraceMs must be a non-negative finite number");
-  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1) throw new RangeError("maxOutputBytes must be a positive integer");
-  const live = new Set<LiveRun>();
-  const children = new Set<Child>();
-  let destroyed = false;
-
-  const abortedError = (taskName: string, cause?: unknown): OffloadError =>
-    new OffloadError({ kind: "aborted", taskName, message: `${taskName} was aborted`, cause });
-  const destroyedError = (taskName: string): OffloadError =>
-    new OffloadError({ kind: "aborted", taskName, message: `${taskName} was cancelled: subprocess runner destroyed` });
-
-  return {
-    offThread: true,
-    get stats() { return { active: queue.pending, queued: queue.size }; },
-    async run(taskName: string, spec: SubprocessSpec, env?: OffloadEnvelope): Promise<SubprocessResult> {
-      const labels = env?.labels ?? {};
-      const logger = env?.logger ?? options.logger;
-      const sink = env?.onEscalate ?? options.onEscalate;
-      const reportRejection = async (error: OffloadError): Promise<never> => {
-        // Rejecting before the run reaches startLog is still a terminal outcome; without this
-        // the structured stream shows nothing at all for it.
-        finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
-        await recordResult({ counter, taskName, backend: "subprocess", labels, error, sink, logger });
-        throw error;
-      };
-      if (!spec.command.length) return reportRejection(new OffloadError({ kind: "rejected", taskName, message: "Subprocess command must not be empty" }));
-      if (destroyed) return reportRejection(destroyedError(taskName));
-      if (env?.signal?.aborted) return reportRejection(abortedError(taskName, env.signal.reason));
-      try {
-        validateTimeout(env?.timeoutMs ?? options.defaultTimeoutMs);
-      } catch (error) {
-        return reportRejection(normalizeError(taskName, error, "rejected"));
-      }
-
-      let publish!: (outcome: Outcome) => void;
-      let published = false;
-      const outcome = new Promise<Outcome>((resolve) => {
-        publish = (value) => { if (!published) { published = true; resolve(value); } };
-      });
-      let started = false;
-      let cancelled = false;
-      const entry: LiveRun = {
-        taskName,
-        teardown: new AbortController(),
-        settled: outcome.then(() => undefined),
-        cancelIfQueued: (error) => {
-          if (started || cancelled) return;
-          cancelled = true;
-          // The single funnel for both abort-while-queued and destroy()-cancels-queued, so
-          // the one line each terminal path owes the structured stream is emitted here. The
-          // callback bails on `cancelled` without logging, which keeps it to exactly one.
-          finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
-          publish({ ok: false, error });
-        },
-      };
-      live.add(entry);
-
-      // p-queue's own `signal` option used to provide prompt abort for queued runs, but it
-      // also released the slot while the child kept running (#1809 P1-7).
-      const signal = env?.signal;
-      const onQueuedAbort = signal ? () => entry.cancelIfQueued(abortedError(taskName, signal.reason)) : undefined;
-      if (signal && onQueuedAbort) signal.addEventListener("abort", onQueuedAbort, { once: true });
-
-      const task = queue.add(async () => {
-        if (signal && onQueuedAbort) signal.removeEventListener("abort", onQueuedAbort);
-        let context: RunContext | undefined;
-        let child: Child | undefined;
-        let onAbort: (() => void) | undefined;
-        let killTimer: ReturnType<typeof setTimeout> | undefined;
-        let abandonTimer: ReturnType<typeof setTimeout> | undefined;
-        let reaped = false;
-        let abandon!: () => void;
-        const abandoned = new Promise<"abandoned">((resolve) => { abandon = () => resolve("abandoned"); });
-        try {
-          if (cancelled) return;
-          if (destroyed || entry.teardown.signal.aborted) {
-            const error = destroyedError(taskName);
-            finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
-            publish({ ok: false, error });
-            return;
-          }
-          started = true;
-          context = beginRun(taskName, env, options, entry.teardown.signal);
-          const run = context;
-          const startedAt = startLog(logger, "subprocess", taskName, labels);
-          // SIGTERM alone bounds nothing: a child that traps or ignores it runs to completion
-          // while holding the slot (#1809 P0-3). Escalate to a group SIGKILL, then stop
-          // waiting altogether so the deadline is real even for an unkillable child.
-          onAbort = () => {
-            if (!child || reaped) return;
-            killGroup(child, "SIGTERM");
-            killTimer = setTimeout(() => {
-              // `reaped` keeps a late timer from signalling a process group whose pid the
-              // kernel may already have handed to somebody else.
-              if (!child || reaped) return;
-              killGroup(child, "SIGKILL");
-              abandonTimer = setTimeout(abandon, REAP_GRACE_MS);
-            }, killGraceMs);
-          };
-          run.signal.addEventListener("abort", onAbort, { once: true });
-          try {
-            if (run.signal.aborted) throw run.abortError();
-            child = Bun.spawn(spec.command, {
-              cwd: spec.cwd,
-              env: spec.env ? { ...process.env, ...spec.env } : process.env,
-              stdin: "ignore", stdout: "pipe", stderr: "pipe",
-              detached: process.platform !== "win32",
-            });
-            trackChild(child);
-            children.add(child);
-            const exiting = child;
-            void exiting.exited.then(() => {
-              reaped = true;
-              liveChildren.delete(exiting);
-              children.delete(exiting);
-            });
-            const completed = Promise.all([
-              readCapped(child.stdout as ReadableStream<Uint8Array> | null, maxOutputBytes),
-              readCapped(child.stderr as ReadableStream<Uint8Array> | null, maxOutputBytes),
-              child.exited,
-            ]);
-            const settledRun = await Promise.race([completed, abandoned]);
-            if (settledRun === "abandoned") {
-              throw run.signal.aborted
-                ? run.abortError()
-                : new OffloadError({ kind: "timeout", taskName, message: `${taskName} did not exit after SIGKILL` });
-            }
-            const [stdout, stderr, exitCode] = settledRun;
-            if (run.signal.aborted) throw run.abortError();
-            const okExitCodes = spec.okExitCodes ?? [0];
-            if (okExitCodes !== "any" && !okExitCodes.includes(exitCode)) throw new OffloadError({
-              kind: "rejected", taskName, code: String(exitCode), message: `${taskName} exited ${exitCode}: ${stderr.text.trim() || stdout.text.trim()}`,
-            });
-            const result: SubprocessResult = { exitCode, stdout: stdout.text, stderr: stderr.text, truncated: stdout.truncated || stderr.truncated };
-            finishLog(logger, "subprocess", taskName, labels, startedAt);
-            await recordResult({ counter, taskName, backend: "subprocess", labels, sink, logger });
-            publish({ ok: true, value: result });
-          } catch (error) {
-            const normalized = run.signal.aborted ? run.abortError() : normalizeError(taskName, error);
-            finishLog(logger, "subprocess", taskName, labels, startedAt, normalized);
-            await recordResult({ counter, taskName, backend: "subprocess", labels, error: normalized, sink, logger });
-            publish({ ok: false, error: normalized });
-          } finally {
-            if (onAbort) run.signal.removeEventListener("abort", onAbort);
-            run.cleanup();
-          }
-        } catch (error) {
-          const normalized = normalizeError(taskName, error, "rejected");
-          finishLog(logger, "subprocess", taskName, labels, performance.now(), normalized);
-          await recordResult({ counter, taskName, backend: "subprocess", labels, error: normalized, sink, logger });
-          publish({ ok: false, error: normalized });
-        } finally {
-          context?.cleanup();
-          // Keep the slot until the child is actually reaped, so the concurrency cap and
-          // `stats` stay true while a kill is in flight (#1809 P1-7). `abandoned` bounds
-          // this: the SIGKILL escalation above always ends the wait.
-          if (child) await Promise.race([child.exited, abandoned]);
-          if (killTimer) clearTimeout(killTimer);
-          if (abandonTimer) clearTimeout(abandonTimer);
-          live.delete(entry);
-        }
-      });
-      void task.catch(() => undefined);
-
-      const result = await outcome;
-      if (!result.ok) throw result.error;
-      return result.value;
-    },
-    drain: () => queue.onIdle(),
-    async destroy(): Promise<void> {
-      destroyed = true;
-      const outstanding = [...live];
-      for (const entry of outstanding) {
-        entry.cancelIfQueued(destroyedError(entry.taskName));
-        entry.teardown.abort(new DOMException("Subprocess runner destroyed", "AbortError"));
-      }
-      for (const child of children) killGroup(child, "SIGKILL");
-      await Promise.all([
-        ...outstanding.map((entry) => entry.settled),
-        ...[...children].map((child) => child.exited),
-      ]);
-    },
-  };
-}