@vzn/vx 0.0.650 → 0.0.651

package/src/cli/why.ts

@@ -18,19 +18,9 @@ import {
   whyDidThisRerun,
 } from '../history/index.js'
 import { resolveRunId } from '../orchestrator/index.js'
-import {
-  detectColors,
-  ERROR,
-  MASKED,
-  nearMatches,
-  paint,
-  printable,
-  refusal,
-  SUCCESS,
-  ui,
-  UserError,
-  WARN,
-} from '../util/index.js'
+import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import type { Style } from '../ui/index.js'
 import { runRules } from '../settings.js'
 import { buildPackageGraph, findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
@@ -165,6 +155,7 @@ async function resolveTarget(
   cache: Cache,
   target: string,
   cwdProject: () => Promise<string | null>,
+  declared: () => Promise<boolean>,
 ): Promise<string> {
   const db = indexDb(cache)
   if (target.includes('#')) {
@@ -202,11 +193,21 @@ async function resolveTarget(
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
   if (ids.length === 0 && !invoked) {
+    // `vx run` of a task no project declares is refused: its advice was that.
+    const known = await declared()
     throw refusal(
-      { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` },
+      known
+        ? { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` }
+        : {
+            tone: 'info',
+            headline: `no project declares ${target}`,
+            fix: 'vx show lists the tasks',
+          },
       {
         code: 'VX_E_NO_HISTORY',
-        message: `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,
+        message: known
+          ? `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`
+          : `vx why: no project declares "${target}" (vx show lists the tasks)`,
       },
     )
   }
@@ -264,8 +265,12 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
   try {
     const db = indexDb(cache)
-    const taskId = await resolveTarget(cache, await rootSpelled(root, parsed.target), () =>
-      findCwdProject(process.cwd()),
+    const target = await rootSpelled(root, parsed.target)
+    const taskId = await resolveTarget(
+      cache,
+      target,
+      () => findCwdProject(process.cwd()),
+      () => declares(root, target),
     )
     let runId: string | null
     if (parsed.runId !== undefined) {
@@ -290,14 +295,23 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       // the persisted entry metadata so the verb still says something useful.
       const explanation = explainCacheKey(db, taskId)
       if (parsed.format === 'json') {
-        process.stdout.write(`${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
+        ui.data('out', `${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
       } else {
-        const c = detectColors(process.stdout)
-        process.stdout.write(
-          `${ui.inline(ui.id(taskId), c)}: recorded runs carry no run id — showing the latest cache entry instead\n` +
-            (explanation.latestEntry !== null
-              ? `  hash ${explanation.latestEntry.hash} · $ ${explanation.latestEntry.command}\n`
-              : '  (no cache entry either)\n'),
+        ui.print(
+          'out',
+          ui.section(
+            'Why',
+            taskId,
+            ui.text('recorded runs carry no run id: the latest cache entry instead'),
+            ui.fields(
+              explanation.latestEntry !== null
+                ? [
+                    ['key', explanation.latestEntry.hash],
+                    ['command', ui.cmd(explanation.latestEntry.command)],
+                  ]
+                : [['key', 'no cache entry either']],
+            ),
+          ),
         )
       }
       return 0
@@ -326,27 +340,22 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const writers = inputWriters(db, root, taskId, diff.entries, roots)
 
     if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
+      ui.data('out', `${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
       return 0
     }
 
-    const lines: string[] = []
-    const c = detectColors(process.stdout)
-    const dim = (text: string): string => paint('', text, c, { dim: true })
-    const head = (text: string): string => paint('', text, c, { bold: true })
     const t = why.thisRun!
-    lines.push(`${ui.inline(ui.id(taskId), c)}${dim(` — run ${runId}`)}`)
-    lines.push(`  ${dim('this run')}   ${runFacts(t)}`)
+    const head: ui.FieldRow[] = [
+      ['run', runId],
+      ['this run', runFacts(t)],
+    ]
     if (why.previousRun == null && t.hash === '') {
       // Only keyed runs are compared: a persistent task's tenth run read
       // as its first, and the note saying why went unprinted.
-      lines.push(`  ${dim('previous')}   (none with a cache key)`)
-      lines.push(`  ${dim('verdict')}    ${why.note}`)
+      head.push(['previous', 'none with a cache key'], ['verdict', why.note])
     } else if (why.previousRun == null) {
-      lines.push(`  ${dim('previous')}   (none — first recorded run of this task)`)
+      head.push(['previous', 'none: first recorded run of this task'])
     } else {
-      const p = why.previousRun
-      lines.push(`  ${dim('previous')}   ${runFacts(p)}`)
       // The key moved and the diff says by what: the verdict names it, so
       // an env-only change reads as one line, not "inputs differ" above a
       // table to scan.
@@ -354,56 +363,71 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       const moved = diff.entries.map((e) =>
         e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
       )
-      lines.push(
-        `  ${dim('verdict')}    ${
+      head.push(
+        ['previous', runFacts(why.previousRun)],
+        [
+          'verdict',
           why.hashChanged === true && moved.length > 0
-            ? paint(
-                WARN,
+            ? ui.tone(
+                'warn',
                 `cache key changed: ${moved.slice(0, 3).join(', ')}${moved.length > 3 ? ` and ${moved.length - 3} more` : ''}`,
-                c,
               )
-            : why.note
-        }`,
+            : why.note,
+        ],
       )
     }
+    if (diff.entries.length === 0 && why.hashChanged === true) head.push(['detail', diff.note])
+    const blocks: ui.Block[] = [ui.section('Why', taskId, ui.fields(head))]
 
     if (diff.entries.length > 0) {
-      lines.push('')
-      lines.push(
-        `  ${head('what changed')}${dim(` (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged)`)}:`,
+      blocks.push(
+        ui.section(
+          'What changed',
+          `${diff.entries.length} of ${diff.entries.length + diff.unchangedCount}`,
+          ui.table(
+            ['change', 'kind', 'name', 'before → after'],
+            diff.entries.map((e) => [
+              ui.tone(CHANGE_HUE[e.change] ?? 'warn', e.change),
+              e.kind,
+              ui.strong(printable(e.name)),
+              // A secret-named env input shows its name and its change, no hash.
+              e.before === MASKED || e.after === MASKED
+                ? ''
+                : e.change === 'added'
+                  ? `+ ${e.after}`
+                  : e.change === 'removed'
+                    ? `- ${e.before}`
+                    : `${e.before} → ${e.after}`,
+            ]),
+          ),
+        ),
       )
-      const kindW = Math.max(...diff.entries.map((e) => e.kind.length), 4)
-      for (const e of diff.entries) {
-        // A secret-named env input shows its name and its change, no hash.
-        const beforeAfter =
-          e.before === MASKED || e.after === MASKED
-            ? ''
-            : e.change === 'added'
-              ? `+ ${e.after}`
-              : e.change === 'removed'
-                ? `- ${e.before}`
-                : `${e.before} → ${e.after}`
-        lines.push(
-          `    ${paint(CHANGE_HUE[e.change] ?? WARN, e.change.padEnd(7), c)} ${dim(e.kind.padEnd(kindW))}  ${printable(e.name)}  ${dim(beforeAfter)}`.trimEnd(),
-        )
-      }
       if (roots.length > 0) {
-        lines.push('', `  ${head('root cause')}:`)
-        for (const r of roots.slice(0, ROOTS_SHOWN)) {
+        const lines: ui.Inline[] = roots.slice(0, ROOTS_SHOWN).map((r) => {
           const what = r.entries.map((e) =>
             e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
           )
-          lines.push(
-            `    ${r.chain.join(' \u2190 ')} \u2190 ${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
-          )
-        }
-        if (roots.length > ROOTS_SHOWN) lines.push(`    and ${roots.length - ROOTS_SHOWN} more`)
+          return [
+            ...r.chain.flatMap((id, i) => [...(i > 0 ? [ui.dim(' \u2190 ')] : []), ui.id(id)]),
+            ui.dim(' \u2190 '),
+            ui.strong(
+              `${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
+            ),
+          ]
+        })
+        if (roots.length > ROOTS_SHOWN) lines.push(`and ${roots.length - ROOTS_SHOWN} more`)
+        blocks.push(ui.section('Root cause', ui.text(...lines)))
       }
       if (writers.length > 0) {
-        lines.push('', `  ${head('changed during a run')}:`)
-        for (const w of writers) {
-          lines.push(`    ${printable(w.file)}  ${dim(`while ${w.writers.join(', ')} ran`)}`)
-        }
+        blocks.push(
+          ui.section(
+            'Changed during a run',
+            ui.table(
+              ['file', 'written while'],
+              writers.map((w) => [ui.path(printable(w.file)), w.writers.join(', ')]),
+            ),
+          ),
+        )
       }
       const rootKinds = roots.flatMap((r) => r.entries.map((e) => e.kind))
       // An upstream row names the task to ask next: the command, not a
@@ -418,31 +442,26 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
           k in WHAT_TO_DO && !(k === 'upstream' && (roots.length > 0 || upstream.length === 0)),
       )
       if (kinds.length > 0) {
-        lines.push('', `  ${head('what to do')}:`)
-        // Its own column: a root cause's kind and the `written` row are
-        // not in the table above, and overflowed its width.
-        const todoW = Math.max(kindW, ...kinds.map((k) => k.length), writers.length > 0 ? 7 : 0)
+        const todo: ui.FieldRow[] = []
         for (const k of kinds) {
           if (k === 'upstream') {
-            for (const todo of upstream) lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
+            todo.push([k, ...upstream])
             continue
           }
-          const todo =
+          todo.push([
+            k,
             k === 'config'
               ? WHAT_TO_DO[k]!.replace('`vx show <that task>`', `\`vx show ${taskId}\``)
-              : WHAT_TO_DO[k]
-          lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
-        }
-        if (writers.length > 0) {
-          // A task re-writing a file a key reads moves that key every run:
-          // the miss is right, and only moving the write ends it.
-          lines.push(`    ${dim('written'.padEnd(todoW))}  ${WRITTEN_TODO}`)
+              : WHAT_TO_DO[k]!,
+          ])
         }
+        // A task re-writing a file a key reads moves that key every run:
+        // the miss is right, and only moving the write ends it.
+        if (writers.length > 0) todo.push(['written', WRITTEN_TODO])
+        blocks.push(ui.section('What to do', ui.fields(todo)))
       }
-    } else if (why.hashChanged === true) {
-      lines.push(`  ${dim('detail')}     ${diff.note}`)
     }
-    process.stdout.write(`${lines.join('\n')}\n`)
+    ui.print('out', ...blocks)
     return 0
   } finally {
     cache.close()
@@ -451,7 +470,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 
 const ROOTS_SHOWN = 5
 
-const CHANGE_HUE: Record<string, string> = { added: SUCCESS, removed: ERROR, changed: WARN }
+const CHANGE_HUE: Record<string, Style> = { added: 'ok', removed: 'error', changed: 'warn' }
 
 type DiffEntry = ReturnType<typeof cacheKeyDiff>['entries'][number]
 
@@ -489,6 +508,21 @@ function upstreamTodo(upstream: readonly DiffEntry[], unrecorded: readonly DiffE
   return out
 }
 
+/** Whether a project declares `target` (`pkg#task`, or a bare task); true when no config loads. */
+async function declares(root: string, target: string): Promise<boolean> {
+  try {
+    const projects = await loadCliProjects(root, await discoverCliProjects(root), 'all')
+    const [project, task] = target.includes('#') ? splitTaskId(target) : [undefined, target]
+    return [...projects.values()].some(
+      (p) =>
+        (project === undefined || p.name === project) && Object.hasOwn(p.config.tasks ?? {}, task),
+    )
+  } catch {
+    // quiet: with no lock or a broken config, the run says why itself
+    return true
+  }
+}
+
 /**
  * Each group in `taskId`'s graph with the tasks it gathers. Empty when a
  * config no longer loads: the advice then names the group to `vx show`.

package/src/cli/workspace-config.ts

@@ -7,7 +7,8 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { UserError, sayLine } from '../util/index.js'
+import { UserError } from '../util/index.js'
+import { sayLine } from '../ui/index.js'
 import {
   discoverProjects,
   loadProjects,

package/src/exec/executor.ts

@@ -16,7 +16,8 @@
 import type { SandboxConfig } from '../config.js'
 import type { CaptureConfig, RunResult } from './runner.js'
 import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
-import { thrownMessage, UserError, type ui } from '../util/index.js'
+import { thrownMessage, UserError } from '../util/index.js'
+import * as ui from '../ui/index.js'
 
 /** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
 export interface ExecuteSandbox {

package/src/exec/kill-tree.ts

@@ -98,6 +98,9 @@ let guardProc: Child | undefined
  */
 const GUARD_STALL_MS = 1_000
 
+/** Bytes per write to the guard: under a socket's buffer on every platform. */
+const GUARD_PIECE = 1024
+
 function startGuard(): void {
   if (guardFd !== undefined) return
   guardFd = null
@@ -114,6 +117,8 @@ function startGuard(): void {
     const fd = guard.stdio[3] as number
     guardFd = fd
     guardProc = guard
+    // A clean exit strikes what it released: the EOF kills what is listed.
+    process.once('exit', flushGuard)
     // A guard that has died (killed, the OOM killer) is handed to no later
     // spawn: its pipe is broken, and a shell whose printf buffers (bash as
     // macOS's sh) flushed the failed `+<pgid>` line into the task's own
@@ -134,6 +139,7 @@ function startGuard(): void {
 function stopGuard(): void {
   const fd = guardFd
   guardFd = null
+  pending = ''
   guardProc?.kill('SIGKILL')
   if (typeof fd !== 'number') return
   try {
@@ -145,11 +151,18 @@ function stopGuard(): void {
 
 function guardWrite(line: string): void {
   if (typeof guardFd !== 'number') return
-  const deadline = Date.now() + GUARD_STALL_MS
+  let deadline = Date.now() + GUARD_STALL_MS
+  // A turn's batch can be more than the queue takes at once: it goes in
+  // pieces as the guard drains it, and only a guard that takes nothing for
+  // the whole stall is gone. With one deadline for the batch, 2000 strikes
+  // outlasted it on macOS and the guard was stopped under a live run.
+  let bytes = Buffer.from(line)
   for (;;) {
     try {
-      writeSync(guardFd, line)
-      return
+      const n = writeSync(guardFd, bytes, 0, Math.min(bytes.length, GUARD_PIECE))
+      if (n === bytes.length) return
+      bytes = bytes.subarray(n)
+      deadline = Date.now() + GUARD_STALL_MS
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== 'EAGAIN' || Date.now() >= deadline) break
       Bun.sleepSync(1)
@@ -158,6 +171,43 @@ function guardWrite(line: string): void {
   stopGuard()
 }
 
+/**
+ * Lines waiting for this turn's one write: strikes, and the listings of
+ * spare shells. Each line was a write of its own and a wake of the
+ * guard's shell: on a cold run of 500 tasks, 38 ms of vx's main thread
+ * for the strikes and 140 ms of the guard's CPU (2026-11-03). If vx dies
+ * in the turn a task ended, what that task left in the background dies
+ * with it, as when vx dies a moment before the task ends.
+ */
+let pending = ''
+let pendingTimer: ReturnType<typeof setImmediate> | undefined
+
+function queueLine(line: string): void {
+  pending += line
+  pendingTimer ??= setImmediate(flushGuard)
+}
+
+/** Write the lines this turn queued now: before a listed child is handed its work. */
+export function flushGuard(): void {
+  if (pendingTimer !== undefined) clearImmediate(pendingTimer)
+  pendingTimer = undefined
+  const lines = pending
+  pending = ''
+  if (lines !== '') guardWrite(lines)
+}
+
+/**
+ * List `pid`'s group from vx's side, for a child that runs nothing until
+ * vx hands it work (a spare shell waiting on its script): the line goes
+ * with the turn's others, and `flushGuard` before the hand-over. A spare
+ * vx dies before listing reads the end of its script's pipe and exits,
+ * having run nothing. Starts the guard.
+ */
+export function listGroup(pid: number): void {
+  startGuard()
+  if (typeof guardFd === 'number' && pid > 0) queueLine(`+${pid}\n`)
+}
+
 /**
  * Spawn a task child whose group the guard kills if vx dies holding it.
  * The CHILD lists its own group, before it runs anything: vx wrote the
@@ -170,8 +220,11 @@ function guardWrite(line: string): void {
  * races it. The guard starts BEFORE the spawn, so there is a pipe to hand.
  * `undefined` when the guard could not start: nothing lists anything.
  */
-export function spawnGuarded(spawn: (guard: number | undefined) => Child): Child {
+export function spawnGuarded<C = Child>(spawn: (guard: number | undefined) => C): C {
   startGuard()
+  // The turn's lines go first, as they did one write each: a child's own
+  // listing behind them, not raced by a batch vx writes once it runs.
+  flushGuard()
   if (typeof guardFd !== 'number') return spawn(undefined)
   handingTo = guardProc?.pid
   try {
@@ -223,7 +276,7 @@ export function releaseGroup(child: Child): void {
   if (!(child.pid > 0)) return
   const hold = holds.get(child.pid)
   if (hold !== undefined) hold.released = true
-  else guardWrite(`-${child.pid}\n`)
+  else queueLine(`-${child.pid}\n`)
 }
 
 /**

package/src/exec/local-executor.ts

@@ -44,6 +44,7 @@ export function localExecutor(): TaskExecutor {
         ...(req.liveChildren !== undefined ? { liveChildren: req.liveChildren } : {}),
         ...(req.onSpawn !== undefined ? { onSpawn: req.onSpawn } : {}),
         ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+        ...(req.signal !== undefined ? { signal: req.signal } : {}),
       }
       if (req.sandbox === undefined) {
         const res = await runCommand(req.terminal === true ? { ...common, terminal: true } : common)
@@ -56,7 +57,6 @@ export function localExecutor(): TaskExecutor {
         reportWithin: req.sandbox.reportWithin,
         reportLinked: req.sandbox.reportLinked,
         config: req.sandbox.config,
-        ...(req.signal !== undefined ? { signal: req.signal } : {}),
       })
     },
   }

package/src/exec/pipes.ts

@@ -0,0 +1,152 @@
+// A task's stdout, stderr and held stdin as pipes vx makes itself (Linux),
+// shared by the runner, the spare shells and the sandbox's spawn.
+
+import type { Pointer } from 'bun:ffi'
+import { closeSync } from 'node:fs'
+
+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}. */
+export 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)
+  }
+}