@vzn/vx 0.0.650 → 0.0.651

package/src/exec/runner.ts

@@ -4,8 +4,7 @@
 // process exits. cpuMs / peakRssBytes are then surfaced on RunResult and
 // folded into the v11 `runs` table by the orchestrator.
 
-import type { Pointer } from 'bun:ffi'
-import { closeSync, existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { constants as osConstants } from 'node:os'
 import {
   formatBytes,
@@ -14,10 +13,12 @@ import {
   isOutOfFds,
   killGraceMs,
   OUT_OF_FDS_HINT,
+  testTimerMs,
   helperEnv,
   type SecretMask,
 } from '../util/index.js'
 import {
+  type Child,
   closeSignalChannel,
   holdGroups,
   killTree,
@@ -28,6 +29,10 @@ import {
   spawnGuarded,
   untilGroupsGone,
 } from './kill-tree.js'
+import { type TreeUsage, watchTree } from './proc-sample.js'
+import { TaskPipes } from './pipes.js'
+import { spawnOff } from './spawn-off.js'
+import { runOnSpare, spareScript, takeSpare } from './warm-shell.js'
 
 /** `sh` names itself in its errors. */
 const SH_ARGV0 = { argv0: 'sh' }
@@ -96,6 +101,8 @@ export interface RunOptions {
    * handler can SIGTERM everything still alive mid-run.
    */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /** The run's stop (`ExecuteRequest.signal`): one that lands before the child is in `liveChildren` stops it here. */
+  signal?: AbortSignal
   /** Told the child's pid once it is spawned (telemetry samples its tree). */
   onSpawn?: (pid: number) => void
   /**
@@ -113,153 +120,6 @@ function taskStdio(terminal: boolean | undefined, pipes: TaskPipes): [Fd, Fd, Fd
   return terminal === true ? ['inherit', 'inherit', 'inherit'] : [pipes.stdin, ...pipes.stdio]
 }
 
-const O_NONBLOCK = 0o4000
-const O_CLOEXEC = 0o2000000
-const F_SETFL = 4
-const F_SETPIPE_SZ = 1031
-/**
- * A pipe holds 64 KiB by default, and a 200 MB stdout drained 13% slower
- * through one than through Bun's socketpair (min of 7: 293 vs 259 ms);
- * at 256 KiB it drained in 230. Past the user's pipe quota the kernel
- * refuses the resize and the pipe keeps its 64 KiB.
- */
-const PIPE_BYTES = 256 * 1024
-
-type PipeCalls = {
-  pipe2: (fds: Pointer, flags: number) => number
-  fcntl: (fd: number, cmd: number, arg: number) => number
-  ptr: (view: Int32Array, byteOffset?: number) => Pointer
-}
-let pipeCalls: PipeCalls | null | undefined
-
-/** libc's `pipe2` and `fcntl`, bound once; null off Linux or where libc will not load. */
-function linuxPipeCalls(): PipeCalls | null {
-  if (pipeCalls !== undefined) return pipeCalls
-  pipeCalls = null
-  if (process.platform !== 'linux') return null
-  try {
-    // Loaded at the first spawn, not with the module: a static import cost
-    // every vx start 0.3 ms, a warm run that spawns nothing included.
-    const { dlopen, FFIType, ptr } = require('bun:ffi') as typeof import('bun:ffi')
-    // glibc's soname; musl's loader answers any `libc.` name with itself
-    // (ldso/dynlink.c's reserved names).
-    const { symbols } = dlopen('libc.so.6', {
-      pipe2: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
-      fcntl: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
-    })
-    pipeCalls = { pipe2: symbols.pipe2, fcntl: symbols.fcntl, ptr }
-  } catch {
-    // Bun's socketpair, as before: only `/dev/stdout` by path fails on it.
-  }
-  return pipeCalls
-}
-
-/**
- * Two pipes, `[out read, out write, err read, err write]`, or undefined
- * when libc is not bound or a descriptor is not to be had (Bun's own
- * socketpair then fails the spawn with the reason).
- */
-function realPipes(): Int32Array | undefined {
-  const calls = linuxPipeCalls()
-  if (calls === null) return undefined
-  const fds = new Int32Array(4)
-  // Bun's spawn closes every descriptor it is not handed (probed, Bun
-  // 1.4.2); O_CLOEXEC keeps any other exec from holding a write end open.
-  if (calls.pipe2(calls.ptr(fds), O_CLOEXEC) !== 0) return undefined
-  if (calls.pipe2(calls.ptr(fds, 8), O_CLOEXEC) !== 0) {
-    closeSync(fds[0]!)
-    closeSync(fds[1]!)
-    return undefined
-  }
-  // vx's ends only: a task whose stdout is non-blocking fails its writes with EAGAIN.
-  calls.fcntl(fds[0]!, F_SETFL, O_NONBLOCK)
-  calls.fcntl(fds[2]!, F_SETFL, O_NONBLOCK)
-  calls.fcntl(fds[0]!, F_SETPIPE_SZ, PIPE_BYTES)
-  calls.fcntl(fds[2]!, F_SETPIPE_SZ, PIPE_BYTES)
-  return fds
-}
-
-/** One pipe, `[read, write]`, both close-on-exec, or undefined as {@link realPipes}. */
-function heldPipe(): Int32Array | undefined {
-  const calls = linuxPipeCalls()
-  if (calls === null) return undefined
-  const fds = new Int32Array(2)
-  return calls.pipe2(calls.ptr(fds), O_CLOEXEC) === 0 ? fds : undefined
-}
-
-/**
- * A task's stdout and stderr. Bun's `'pipe'` is a socketpair, and Linux
- * opens `/dev/stdout` through `/proc/self/fd/1`, which a socket refuses
- * (ENXIO): `echo x > /dev/stdout` and `cmd | tee /dev/stderr` failed in
- * every task, where a terminal or Turbo hands real pipes (X-113). So on
- * Linux vx makes the pipes (`pipe2` through `bun:ffi`) and hands the child
- * the write ends. macOS opens `/dev/fd/N` as a dup of the descriptor,
- * which a socket allows, so Bun's pipe stays there.
- *
- * `held`: stdin is a pipe vx keeps open and never writes (a persistent
- * task's, schema.md), for the same reason: `cat /dev/stdin` on Bun's
- * socketpair failed with ENXIO instead of blocking. Otherwise `'ignore'`.
- */
-export class TaskPipes {
-  /** Descriptor 0 for `Bun.spawn`'s `stdio`. */
-  readonly stdin: number | 'pipe' | 'ignore'
-  /** Descriptors 1 and 2 for `Bun.spawn`'s `stdio`. */
-  readonly stdio: readonly [number | 'pipe', number | 'pipe']
-  readonly #read: readonly number[]
-  readonly #stdinWrite: number | undefined
-
-  constructor(terminal?: boolean, held?: boolean) {
-    const fds = terminal === true ? undefined : realPipes()
-    this.stdio = fds === undefined ? ['pipe', 'pipe'] : [fds[1]!, fds[3]!]
-    this.#read = fds === undefined ? [] : [fds[0]!, fds[2]!]
-    const inFds = held === true && terminal !== true ? heldPipe() : undefined
-    this.stdin = held !== true ? 'ignore' : inFds === undefined ? 'pipe' : inFds[0]!
-    this.#stdinWrite = inFds?.[1]
-  }
-
-  /**
-   * Close vx's copies of the child's ends once the spawn has returned or
-   * thrown: the child holds its own, and a write end left here is a writer
-   * the reader's EOF would wait for.
-   */
-  spawned(): void {
-    for (const fd of [this.stdin, ...this.stdio]) if (typeof fd === 'number') closeSync(fd)
-  }
-
-  /** The child's stdout and stderr. */
-  streams(
-    child: ReturnType<typeof Bun.spawn>,
-  ): [
-    ReadableStream<Uint8Array> | number | undefined,
-    ReadableStream<Uint8Array> | number | undefined,
-  ] {
-    const [out, err] = this.#read
-    return out === undefined
-      ? [child.stdout, child.stderr]
-      : [Bun.file(out).stream(), Bun.file(err!).stream()]
-  }
-
-  /**
-   * Close the read ends, once both streams have ended or been cancelled.
-   * Bun reads a dup of each, but takes it on the stream's first pull: a
-   * number closed before then was reused by the next spawn's pipe, and
-   * the stream read THAT (probed, Bun 1.4.2).
-   */
-  close(): void {
-    for (const fd of this.#read) closeSync(fd)
-  }
-
-  /**
-   * Close the held stdin's write end, once the child has exited and its
-   * output has ended. Not with the output alone: a server that sends it
-   * to a log (`exec >log 2>&1`) ended its streams at once, read stdin EOF
-   * and exited.
-   */
-  closeStdin(): void {
-    if (this.#stdinWrite !== undefined) closeSync(this.#stdinWrite)
-  }
-}
-
 /**
  * Read the terminal's modes before a task that holds it runs, and return
  * what puts them back once it exits: a task killed in raw mode (or one
@@ -711,10 +571,28 @@ export const POST_EXIT_CUT_LINE =
   `still held its stdout/stderr ${POST_EXIT_DRAIN_MS} ms later\n`
 
 /**
- * A task's two output callbacks, wrapped to learn whether its output so far
- * ends mid-line, so a line vx adds after it (`POST_EXIT_CUT_LINE`) breaks
- * the line only then: a newline always before it printed a blank line under
- * the task's last line. An absent callback stays absent (nothing decodes).
+ * How long one stream's output waits on the other's open line. dash writes
+ * the pieces of `sh: 1: cannot open /dev/tty: …` back to back; a line open
+ * longer is a prompt or a progress line, and the other stream's lines are
+ * shown live rather than held behind it.
+ */
+export const OPEN_LINE_WAIT_MS = 50
+/** And how much of it waits: the hold never costs more than this per task. */
+export const OPEN_LINE_HOLD_CHARS = 64 * 1024
+
+/**
+ * A task's two output callbacks, merged a line at a time. They are two
+ * pipes, read in the order they arrive, and dash's stderr line written in
+ * pieces took a stdout write inside it: `sh: /dev/ttyNO-TTY\n\n` (CI,
+ * 2026-10-29). So a chunk on one stream waits while the other's line is
+ * open, and goes once that line ends; what of a chunk follows its last
+ * newline goes after the held output. Past `OPEN_LINE_WAIT_MS`,
+ * `OPEN_LINE_HOLD_CHARS` or `end` it goes as written, the line unbroken:
+ * a newline put there became the stream's own text, and a hit replays
+ * each stream to its own descriptor (`2> log` read one the task never
+ * wrote). `own` breaks the line before vx's own text only. A stream
+ * writing alone is never held, so a task that writes one stream pays a
+ * comparison per chunk. An absent callback stays absent (nothing decodes).
  */
 export function lineEnds(
   onStdout?: (chunk: string) => void,
@@ -724,18 +602,74 @@ export function lineEnds(
   onStderr?: (chunk: string) => void
   /** `text` on a line of its own. */
   own(text: string): string
+  /** Lets what waits go: the task's streams ended. */
+  end(): void
 } {
-  let mid = false
-  const track =
-    (f: (chunk: string) => void) =>
-    (chunk: string): void => {
-      if (chunk.length > 0) mid = !chunk.endsWith('\n')
-      f(chunk)
+  // A test lengthens it to drive the hold itself on a loaded runner, where
+  // a `sleep` between two writes outlasted 50 ms (macOS CI, PR #4867).
+  const waitMs = testTimerMs('OPEN_LINE_WAIT', OPEN_LINE_WAIT_MS)
+  const sinks = [onStdout, onStderr]
+  /** The stream whose line is open (0 stdout, 1 stderr). */
+  let open: 0 | 1 | undefined
+  /** What the other stream wrote while that line was open: one side at most. */
+  const held = ['', '']
+  /** When what waits began to: the bound counts from there. */
+  let heldAt = 0
+  // One timer, re-armed only when it fires early: a hold set and cleared
+  // its own per line, and a task interleaving short lines paid a timer each
+  // (+26 ms of CPU on 20 000 lines, 2026-10-29).
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const arm = (ms: number): void => {
+    timer = setTimeout(due, ms)
+    timer.unref()
+  }
+  const due = (): void => {
+    timer = undefined
+    const s = held[0]!.length > 0 ? 0 : held[1]!.length > 0 ? 1 : undefined
+    if (s === undefined) return
+    const left = heldAt + waitMs - performance.now()
+    if (left > 0) arm(left)
+    else release(s)
+  }
+  const write = (s: 0 | 1, text: string): void => {
+    open = text.endsWith('\n') ? undefined : s
+    sinks[s]?.(text)
+  }
+  const release = (s: 0 | 1): void => {
+    const text = held[s]!
+    if (text.length === 0) return
+    held[s] = ''
+    write(s, text)
+  }
+  const push = (s: 0 | 1, chunk: string): void => {
+    if (chunk.length === 0) return
+    if (open === undefined || open === s) {
+      const other = s === 0 ? 1 : 0
+      const nl = held[other]!.length === 0 ? -1 : chunk.lastIndexOf('\n')
+      if (nl === -1 || nl === chunk.length - 1) {
+        write(s, chunk)
+        if (nl !== -1) release(other)
+        return
+      }
+      write(s, chunk.slice(0, nl + 1))
+      release(other)
+      return push(s, chunk.slice(nl + 1))
     }
+    if (held[s]!.length === 0) heldAt = performance.now()
+    held[s] += chunk
+    if (held[s]!.length > OPEN_LINE_HOLD_CHARS) return release(s)
+    if (timer === undefined) arm(waitMs)
+  }
   return {
-    ...(onStdout && { onStdout: track(onStdout) }),
-    ...(onStderr && { onStderr: track(onStderr) }),
-    own: (text) => (mid ? `\n${text}` : text),
+    ...(onStdout && { onStdout: (chunk: string) => push(0, chunk) }),
+    ...(onStderr && { onStderr: (chunk: string) => push(1, chunk) }),
+    own: (text) => (open !== undefined ? `\n${text}` : text),
+    end: () => {
+      clearTimeout(timer)
+      timer = undefined
+      release(0)
+      release(1)
+    },
   }
 }
 
@@ -1151,37 +1085,92 @@ function argTooLongHint(command: string, wrapped: boolean): string {
   )
 }
 
+/** A stop's own sweep, for a child it missed: the polite signal, then SIGKILL past the grace. */
+async function stopLate(proc: Child, signal: 'SIGINT' | 'SIGTERM'): Promise<void> {
+  const letGo = holdGroups([proc])
+  try {
+    killTree(proc, signal)
+    for (const c of await untilGroupsGone([proc], killGraceMs(TIMEOUT_SIGKILL_GRACE_MS)))
+      killTree(c, 'SIGKILL')
+  } finally {
+    letGo()
+  }
+}
+
 export async function runCommand(opts: RunOptions): Promise<RunResult> {
   const start = Date.now()
   const fullCommand = withForwardArgs(opts.command, opts.forwardArgs)
 
-  let proc: ReturnType<typeof Bun.spawn>
-  const pipes = new TaskPipes(opts.terminal)
+  let proc: Child
+  // A spare shell takes the task when there is one (warm-shell.ts).
+  const script =
+    opts.terminal === true ? undefined : spareScript(opts.cwd, opts.env, execWrap(fullCommand))
+  const spare = script === undefined ? undefined : takeSpare()
+  const onSpare = spare === undefined ? undefined : await runOnSpare(spare, script!)
+  const pipes = onSpare === undefined ? new TaskPipes(opts.terminal) : spare!.pipes
   const restoreModes = opts.terminal === true ? keepTerminalModes() : undefined
-  try {
-    proc = spawnGuarded((guard) =>
-      Bun.spawn(shellArgv((guard === undefined ? '' : guardLine(3)) + execWrap(fullCommand)), {
+  if (onSpare !== undefined) proc = onSpare as unknown as Child
+  else
+    try {
+      const stdio = taskStdio(opts.terminal, pipes)
+      const argv = (guard: number | undefined): string[] =>
+        shellArgv((guard === undefined ? '' : guardLine(3)) + execWrap(fullCommand))
+      // Its own session and process group, so a kill reaches what it forked
+      // (kill-tree.ts). A terminal handed over is not this session's
+      // controlling one, so no read stops the group.
+      const spawnOpts = {
         ...SH_ARGV0,
         cwd: opts.cwd,
         env: opts.env as Record<string, string>,
-        stdio: [...taskStdio(opts.terminal, pipes), ...(guard === undefined ? [] : [guard])],
-        // Its own session and process group, so a kill reaches what it
-        // forked (kill-tree.ts). A terminal handed over is not this
-        // session's controlling one, so no read stops the group.
         detached: true,
-      }),
-    )
-  } catch (err) {
-    pipes.close()
-    const stderr = spawnFailureText(err, opts.cwd, 'task', fullCommand)
-    opts.onStderr?.(stderr)
-    return { exitCode: 127, durationMs: Date.now() - start, stdout: '', stderr, spawnFailed: true }
-  } finally {
-    pipes.spawned()
-  }
+      }
+      // Descriptors cross to the spawn thread; Bun's own pipes (macOS) and a
+      // terminal stay on this one.
+      const fds = stdio.filter(
+        (fd): fd is number | 'ignore' => typeof fd === 'number' || fd === 'ignore',
+      )
+      proc =
+        fds.length === stdio.length
+          ? // What vx reads of a child (pid, exit, usage, kill) is the same off
+            // the thread; its streams are the pipes vx made (`TaskPipes`).
+            ((await spawnGuarded((guard) =>
+              spawnOff({
+                cmd: argv(guard),
+                ...spawnOpts,
+                stdio: [...fds, ...(guard === undefined ? [] : [guard])],
+              }),
+            )) as unknown as Child)
+          : spawnGuarded((guard) =>
+              Bun.spawn(argv(guard), {
+                ...spawnOpts,
+                stdio: [...stdio, ...(guard === undefined ? [] : [guard])],
+              }),
+            )
+    } catch (err) {
+      pipes.close()
+      const stderr = spawnFailureText(err, opts.cwd, 'task', fullCommand)
+      opts.onStderr?.(stderr)
+      return {
+        exitCode: 127,
+        durationMs: Date.now() - start,
+        stdout: '',
+        stderr,
+        spawnFailed: true,
+      }
+    } finally {
+      pipes.spawned()
+    }
 
   opts.liveChildren?.add(proc)
+  // The spawn is awaited (off the thread, or on a spare shell), and the
+  // command runs meanwhile: a stop that landed then swept a live set
+  // without it, and the run waited out the whole command (CI, 2026-11-04).
+  if (opts.signal?.aborted === true) void stopLate(proc, stopSignal(opts.signal.reason))
   opts.onSpawn?.(proc.pid)
+  // Linux: the wait's peak includes vx's own, inherited at exec, so a task
+  // lighter than vx reads none (`rssFloorFor`); the tree looked at while it
+  // runs has the task's own.
+  const watch = process.platform === 'linux' ? watchTree(proc.pid) : undefined
   const timeout = armTimeout(proc, opts.timeoutMs)
   const ac = new AbortController()
   const [out, err] = pipes.streams(proc)
@@ -1203,12 +1192,30 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   if (timeout.timedOut()) ac.abort()
   else cut = await drainOrAbort(streams, ac)
   const [stdout, streamed] = await streams
+  ends.end()
   const cutLine = ends.own(POST_EXIT_CUT_LINE)
   if (cut) opts.onStderr?.(cutLine)
   const stderr = cut ? streamed + cutLine : streamed
   opts.liveChildren?.delete(proc)
   releaseGroup(proc)
   const exited = proc.exitCode ?? (proc.signalCode ? signalExitCode(proc.signalCode) : 1)
+  // The spare's `cd` failed: the task never ran, as a spawn into a missing
+  // directory throws. A 127 is the shell's own otherwise.
+  if (onSpare !== undefined && exited === 127 && !existsSync(opts.cwd)) {
+    const text = spawnFailureText(
+      Object.assign(new Error('ENOENT'), { code: 'ENOENT' }),
+      opts.cwd,
+      'task',
+    )
+    opts.onStderr?.(text)
+    return {
+      exitCode: 127,
+      durationMs: Date.now() - start,
+      stdout,
+      stderr: stderr + text,
+      spawnFailed: true,
+    }
+  }
   // A timeout is a failure, whatever the child said: one that traps the
   // TERM and exits 0 reported success to every executor built on this.
   const exitCode = exited === 0 && timeout.timedOut() ? signalExitCode('SIGTERM') : exited
@@ -1220,10 +1227,20 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
     ...(proc.signalCode != null ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
     ...(cut ? { leftRunning: true } : {}),
-    ...resourceUsageToCpuRss(proc.resourceUsage(), rssFloorFor),
+    ...usageOf(proc, watch?.stop()),
   }
 }
 
+/** The CPU and peak a task used: the wait's, and the peak the looks saw when the wait's is vx's own. */
+function usageOf(
+  proc: Child,
+  looked: TreeUsage | undefined,
+): { cpuMs?: number; peakRssBytes?: number } {
+  const usage = resourceUsageToCpuRss(proc.resourceUsage(), rssFloorFor)
+  if (looked === undefined || looked.rssBytes <= 0) return usage
+  return { ...usage, peakRssBytes: Math.max(usage.peakRssBytes ?? 0, looked.rssBytes) }
+}
+
 /**
  * This process's own RSS high-water mark, in bytes: the floor under which
  * a child's `ru_maxrss` says nothing about the child. Linux folds the

package/src/exec/sandbox-binds.ts

@@ -14,7 +14,7 @@ import {
   unique,
 } from './sandbox-paths.js'
 import type { SandboxedRunArgs } from './sandbox-runtime.js'
-import { ui } from '../util/index.js'
+import * as ui from '../ui/index.js'
 
 type SrtModule = typeof import('@anthropic-ai/sandbox-runtime')
 

package/src/exec/sandbox-runtime.ts

@@ -58,10 +58,10 @@ import {
   spawnFailureText,
   streamToString,
   resourceUsageToCpuRss,
-  TaskPipes,
   type CaptureConfig,
   type RunResult,
 } from './runner.js'
+import { TaskPipes } from './pipes.js'
 import { watchTree } from './proc-sample.js'
 import {
   BUN_GLOB_WILDCARDS,
@@ -73,10 +73,10 @@ import {
   isTmpdirRefusal,
   procfsIsOwn,
   TMPDIR_HINT,
-  ui,
   UserError,
   xxh3hex,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import {
   bindableReads,
   bindableWrites,
@@ -2290,6 +2290,7 @@ async function runSandboxedOnce(
   if (timeout.timedOut()) ac.abort()
   else cut = await drainOrAbort(streams, ac)
   const [stdout, streamed] = await streams
+  ends.end()
   const cutLine = ends.own(POST_EXIT_CUT_LINE)
   if (cut) args.onStderr?.(cutLine)
   const stderr = cut ? streamed + cutLine : streamed
@@ -2323,6 +2324,14 @@ async function runSandboxedOnce(
   // (2026-09-05). A sandboxed task that fails must say what it was denied;
   // deciding on the user's behalf that a record was "just traversal" is how
   // a failure ends up with an empty violations section and no explanation.
+  // Linux: the write observer's records reach the store over a Unix socket
+  // this process serves, not with the child's exit. The observer sent them
+  // before the task exited, but a task that ends quickly is seen to exit
+  // in the turn its connection is accepted, before it is read: a turn to
+  // accept and a turn to read take them in (40 fast refused mkdirs at
+  // once: 38 of 200 unreported, 33 with one turn, none with two).
+  if (process.platform === 'linux')
+    for (let turn = 0; turn < 2; turn++) await new Promise((r) => setImmediate(r))
   const records = takeRecords()
   // Read as is on darwin only. Since SRT 0.0.75 the store is fed on Linux
   // too, by the seccomp helper's write observer — but SRT judges those

package/src/exec/spawn-off.ts

@@ -0,0 +1,154 @@
+// A task's spawn on a thread of its own. Bun's spawn holds the calling
+// thread until the child has exec'd (vfork), ~0.6 ms a task, and on a cold
+// run that thread is the scheduler's: 2,000 tasks with 1.8 ms of the
+// scheduler's own work each took 4.96 s spawned there and 3.71 s spawned
+// here, the 3.6 s of that work the floor (2026-10-29). The child's
+// descriptors are numbers in the one table every thread shares, so its
+// pipes are made and read where they were; only the spawn and the wait
+// for its exit move.
+
+import type { ResourceUsage } from 'bun'
+
+/** What `runCommand` reads of a child spawned here. */
+export interface OffChild {
+  readonly pid: number
+  readonly exited: Promise<number>
+  readonly exitCode: number | null
+  readonly signalCode: NodeJS.Signals | null
+  resourceUsage(): ResourceUsage | undefined
+  kill(signal?: NodeJS.Signals | number): void
+  /** Hold the process open from now until the child exits: a spawn with `held: false` does not. */
+  hold(): void
+}
+
+export interface OffSpawn {
+  cmd: string[]
+  argv0?: string
+  cwd?: string
+  env?: Record<string, string>
+  /** Each a descriptor number or `'ignore'`: a stream cannot cross threads. */
+  stdio: Array<number | 'ignore'>
+  detached?: boolean
+  /** False: the child keeps no run alive until `hold()` (a spare shell waiting for its task). */
+  held?: boolean
+}
+
+// The worker as source, not a file: a compiled vx carries only its entry
+// point's graph, and a worker file would need an entry point of its own.
+const WORKER = `
+const live = new Map()
+self.onmessage = (e) => {
+  const m = e.data
+  if (m.kill !== undefined) { live.get(m.kill)?.kill(m.signal); return }
+  let p
+  try {
+    p = Bun.spawn(m.opts.cmd, m.opts)
+  } catch (err) {
+    postMessage({ id: m.id, error: { message: String(err?.message ?? err), code: err?.code } })
+    return
+  }
+  live.set(m.id, p)
+  postMessage({ id: m.id, pid: p.pid })
+  p.exited.then(() => {
+    live.delete(m.id)
+    const u = p.resourceUsage()
+    // Its two fields vx reads: the object itself does not cross threads.
+    const usage = u === undefined ? undefined : { cpuTime: { user: u.cpuTime.user, system: u.cpuTime.system, total: u.cpuTime.total }, maxRSS: u.maxRSS }
+    postMessage({ id: m.id, exitCode: p.exitCode, signalCode: p.signalCode, usage })
+  })
+}
+`
+
+interface Pending {
+  held: () => boolean
+  spawned: (pid: number) => void
+  failed: (err: Error) => void
+  exit: (m: {
+    exitCode: number | null
+    signalCode: NodeJS.Signals | null
+    usage?: ResourceUsage
+  }) => void
+}
+
+let worker: Worker | undefined
+let nextId = 0
+const pending = new Map<number, Pending>()
+let liveCount = 0
+
+function thread(): Worker {
+  if (worker !== undefined) return worker
+  const w = new Worker(URL.createObjectURL(new Blob([WORKER], { type: 'text/javascript' })))
+  w.onmessage = (e: MessageEvent) => {
+    const m = e.data
+    const p = pending.get(m.id)
+    if (p === undefined) return
+    if (m.error !== undefined) {
+      pending.delete(m.id)
+      const err = new Error(m.error.message) as NodeJS.ErrnoException
+      if (m.error.code !== undefined) err.code = m.error.code
+      if (p.held()) settleLive(-1)
+      p.failed(err)
+    } else if (m.pid !== undefined) p.spawned(m.pid)
+    else {
+      pending.delete(m.id)
+      if (p.held()) settleLive(-1)
+      p.exit(m)
+    }
+  }
+  // An idle thread keeps no run alive.
+  w.unref()
+  worker = w
+  return w
+}
+
+/** Hold the process open while a child spawned here runs, as a spawn on the main thread does. */
+function settleLive(delta: number): void {
+  liveCount += delta
+  if (liveCount > 0) worker?.ref()
+  else worker?.unref()
+}
+
+/** Spawn `opts` on the spawn thread; resolves once the child is running, rejects when the spawn threw. */
+export function spawnOff(opts: OffSpawn): Promise<OffChild> {
+  const w = thread()
+  const id = nextId++
+  let held = opts.held !== false
+  if (held) settleLive(1)
+  const { held: _, ...spawn } = opts
+  return new Promise((resolve, reject) => {
+    let exitCode: number | null = null
+    let signalCode: NodeJS.Signals | null = null
+    let usage: ResourceUsage | undefined
+    let onExit!: (code: number) => void
+    const exited = new Promise<number>((r) => (onExit = r))
+    pending.set(id, {
+      held: () => held,
+      failed: reject,
+      spawned: (pid) =>
+        resolve({
+          pid,
+          exited,
+          get exitCode() {
+            return exitCode
+          },
+          get signalCode() {
+            return signalCode
+          },
+          resourceUsage: () => usage,
+          kill: (signal) => w.postMessage({ kill: id, signal }),
+          hold: () => {
+            if (held || exitCode !== null || signalCode !== null) return
+            held = true
+            settleLive(1)
+          },
+        }),
+      exit: (m) => {
+        exitCode = m.exitCode
+        signalCode = m.signalCode
+        usage = m.usage
+        onExit(exitCode ?? 1)
+      },
+    })
+    w.postMessage({ id, opts: spawn })
+  })
+}