@vzn/vx 0.0.18 → 0.0.22

package/src/exec/runner.ts

@@ -4,7 +4,19 @@
 // process exits. cpuMs / peakRssBytes are then surfaced on RunResult and
 // folded into the v11 `runs` table by the orchestrator.
 
+import { existsSync, readFileSync } from 'node:fs'
 import { constants as osConstants } from 'node:os'
+import { executablePath, isExecutableMissing, killGraceMs } from '../util/index.js'
+import {
+  closeSignalChannel,
+  holdGroups,
+  killTree,
+  markGroupIfGone,
+  releaseGroup,
+  signalThrough,
+  spawnGuarded,
+  untilGroupsGone,
+} from './kill-tree.js'
 
 export interface RunResult {
   exitCode: number
@@ -124,21 +136,30 @@ const SHELL_BUILTINS = new Set([
 /**
  * Prepend `exec ` to a command that is a single EXTERNAL program (no
  * shell control characters, not a builtin, no leading env-assignment).
- * `exec` REPLACES the wrapping `sh` with the program, so on a teardown
- * SIGTERM there is no intermediate shell whose death would orphan the
- * real process — the documented grandchild-orphan limitation, resolved
- * for the common single-command case (dev servers: `astro dev`, `vite`,
- * `next dev`; one-shot compilers). It also makes `resourceUsage` measure
- * the program itself rather than the shell. Compound commands, builtins,
- * and `FOO=bar cmd` forms keep the shell (compound-command grandchildren
- * still orphan on a hard programmatic kill — the residual limit every
- * non-cgroup runner shares).
+ * `exec` REPLACES the wrapping `sh` with the program: `resourceUsage`
+ * measures the program itself rather than the shell, a signal lands on
+ * the program directly, and there is one process fewer per task.
+ * (Until kill-tree.ts this was also what kept a single command's real
+ * process from orphaning on a teardown; the process group covers every
+ * shape now.) Compound commands, builtins, and `FOO=bar cmd` forms keep
+ * the shell.
  */
 export function execWrap(command: string): string {
-  if (SHELL_CONTROL.test(command)) return command
+  const first = execWord(command)
+  return first === undefined ? command : `exec ${command}`
+}
+
+/**
+ * The one program a command runs when it is a plain `word args…` — the
+ * word `execWrap` execs, and the word the shell names in "not found" when
+ * it exits 127. Undefined for a pipeline, a builtin, an assignment: there
+ * the 127 could be any segment's.
+ */
+export function execWord(command: string): string | undefined {
+  if (SHELL_CONTROL.test(command)) return undefined
   const first = command.trimStart().split(/\s+/)[0] ?? ''
-  if (first === '' || first.includes('=') || SHELL_BUILTINS.has(first)) return command
-  return `exec ${command}`
+  if (first === '' || first.includes('=') || SHELL_BUILTINS.has(first)) return undefined
+  return first
 }
 
 /**
@@ -153,43 +174,68 @@ export function signalExitCode(signal: string): number {
 }
 
 /**
- * Arm a SIGTERM timeout on a spawned child. Returns a handle whose
- * `timedOut()` reports whether the timer fired — so the caller can
- * classify the resulting SIGTERM as a real failure rather than a
- * Ctrl-C abort — and `clear()` cancels the timer once the child exits
- * on its own. A no-op (never fires, nothing to clear) when `timeoutMs`
- * is undefined.
+ * The reverse: the signal an exit above 128 stands for (137 → SIGKILL),
+ * by the platform's numbering; undefined for a plain exit. The shell
+ * reports 128 + n for a death by signal n, so the read is the shell's
+ * convention, not proof — a command may exit 137 on its own.
  */
+export function exitSignal(code: number): string | undefined {
+  if (code <= 128 || code >= 128 + 65) return undefined
+  const signals = osConstants.signals as Partial<Record<string, number>>
+  const num = code - 128
+  return Object.keys(signals).find((k) => signals[k] === num && !SIGNAL_ALIASES.has(k))
+}
+
+// Second names for one number (SIGIOT = SIGABRT, SIGPOLL = SIGIO); the
+// canonical one reads.
+const SIGNAL_ALIASES = new Set(['SIGIOT', 'SIGPOLL', 'SIGCLD'])
+
 /**
  * Grace after a timeout SIGTERM before escalating to SIGKILL — a child that
  * ignores SIGTERM must still be bounded. Matches the persistent-shutdown grace.
  */
 const TIMEOUT_SIGKILL_GRACE_MS = 2000
 
+/**
+ * Arm a SIGTERM timeout on a spawned child. Returns a handle whose
+ * `timedOut()` reports whether the timer fired — so the caller can
+ * classify the resulting SIGTERM as a real failure rather than a
+ * Ctrl-C abort — and `settle()`, awaited once the child has exited:
+ * it cancels the timers and, when the timeout fired, waits out the rest
+ * of the grace for the child's GROUP and SIGKILLs whoever is left. The
+ * shell dying on the SIGTERM is not the tree dying: a backgrounded
+ * process that ignores it lived on under init after vx exited (nx#11782's
+ * sibling, reproduced on vx 2026-09-24). A no-op (never fires, nothing
+ * to settle) when `timeoutMs` is undefined.
+ */
 export function armTimeout(
   proc: ReturnType<typeof Bun.spawn>,
   timeoutMs: number | undefined,
-): { timedOut: () => boolean; clear: () => void } {
-  if (timeoutMs === undefined) return { timedOut: () => false, clear: () => {} }
-  let fired = false
+): { timedOut: () => boolean; settle: () => Promise<void> } {
+  if (timeoutMs === undefined) return { timedOut: () => false, settle: async () => {} }
+  let firedAt: number | undefined
   let killTimer: ReturnType<typeof setTimeout> | undefined
+  const graceMs = killGraceMs(TIMEOUT_SIGKILL_GRACE_MS)
   const timer = setTimeout(() => {
-    fired = true
-    proc.kill('SIGTERM')
+    firedAt = Date.now()
+    killTree(proc, 'SIGTERM')
     // Escalate to SIGKILL after a grace: a child that TRAPS+IGNORES SIGTERM
     // (`trap '' TERM`) would otherwise defeat the timeout entirely and hang
     // `await proc.exited` until its natural exit — there is no run-level
     // timeout, so a wedged child hangs the whole run forever. Mirrors the
     // end-of-run persistent-shutdown escalation. Unref'd so it never keeps
     // the CLI alive.
-    killTimer = setTimeout(() => proc.kill('SIGKILL'), TIMEOUT_SIGKILL_GRACE_MS)
+    killTimer = setTimeout(() => killTree(proc, 'SIGKILL'), graceMs)
     killTimer.unref?.()
   }, timeoutMs)
   return {
-    timedOut: () => fired,
-    clear: () => {
+    timedOut: () => firedAt !== undefined,
+    settle: async () => {
       clearTimeout(timer)
       if (killTimer !== undefined) clearTimeout(killTimer)
+      if (firedAt === undefined) return
+      const left = await untilGroupsGone([proc], Math.max(0, firedAt + graceMs - Date.now()))
+      for (const child of left) killTree(child, 'SIGKILL')
     },
   }
 }
@@ -203,27 +249,44 @@ export function armTimeout(
  * at once, so the readers win this race immediately and normal tasks pay
  * nothing; only a stuck reader waits out the grace. Residual buffered output is
  * bounded by the OS pipe buffer (streamToString drains continuously DURING the
- * run), so this is far longer than any real drain needs.
+ * run), so this is far longer than any real drain needs. What the leftover
+ * process writes after the bound is lost, and `POST_EXIT_CUT_LINE` says so.
  */
 const POST_EXIT_DRAIN_MS = 250
 
+/**
+ * The line a task's frame gets when the drain bound cut its pipes. The cut
+ * was silent: a backgrounded child's late output vanished from the frame and
+ * the cached replay with no word (nx#35302 reproduced on vx, 2026-09-24).
+ * The bound stays, since it is what keeps a leftover server from hanging the
+ * run; the line makes the loss visible.
+ */
+export const POST_EXIT_CUT_LINE =
+  `\n[vx] output after the task's shell exited was cut: a process it left running ` +
+  `still held its stdout/stderr ${POST_EXIT_DRAIN_MS} ms later\n`
+
 /**
  * After the direct child has exited, wait for the stdout/stderr readers to
  * reach EOF — but bound it: an orphaned grandchild holding the pipe open would
  * hang the run forever (there is no default task timeout). If the grace expires
  * first, abort the reader signal so `streamToString` cancels its read and
- * returns whatever it captured. The timer is cleared AND unref'd so it can
- * never keep the CLI alive after the readers settle (the plugin-flush lesson).
+ * returns whatever it captured, and resolve true: the caller adds
+ * `POST_EXIT_CUT_LINE` to the task's stderr. The timer is unref'd so it can
+ * never keep the CLI alive after the readers settle (the plugin-flush
+ * lesson); it is not cleared, because a late resolve on a race already won
+ * by the drain changes nothing (item 636 deleted the clear and nothing
+ * reddened).
  */
-export async function drainOrAbort(streams: Promise<unknown>, ac: AbortController): Promise<void> {
-  let timer: ReturnType<typeof setTimeout> | undefined
+export async function drainOrAbort(
+  streams: Promise<unknown>,
+  ac: AbortController,
+): Promise<boolean> {
   const deadline = new Promise<'timeout'>((resolve) => {
-    timer = setTimeout(() => resolve('timeout'), POST_EXIT_DRAIN_MS)
-    timer.unref?.()
+    setTimeout(() => resolve('timeout'), POST_EXIT_DRAIN_MS).unref?.()
   })
   const winner = await Promise.race([streams.then(() => 'drained' as const), deadline])
-  if (timer !== undefined) clearTimeout(timer)
   if (winner === 'timeout') ac.abort()
+  return winner === 'timeout'
 }
 
 /**
@@ -233,6 +296,22 @@ export async function drainOrAbort(streams: Promise<unknown>, ac: AbortControlle
  */
 const READY_MATCH_WINDOW_CHARS = 64 * 1024
 
+/**
+ * Why a persistent task never became ready — the reason every label and
+ * record reads instead of a fabricated exit (item 270). `exitCode` is the
+ * child's own when it exited before the pattern matched.
+ */
+export class PersistentReadyError extends Error {
+  readonly reason: 'timeout' | 'exited' | 'spawn'
+  readonly exitCode: number | undefined
+  constructor(message: string, reason: 'timeout' | 'exited' | 'spawn', exitCode?: number) {
+    super(message)
+    this.name = 'PersistentReadyError'
+    this.reason = reason
+    this.exitCode = exitCode
+  }
+}
+
 export interface PersistentSpawn {
   /** Underlying Bun subprocess so the orchestrator can SIGTERM it later. */
   child: ReturnType<typeof Bun.spawn>
@@ -264,6 +343,12 @@ export interface PersistentOptions extends Omit<RunOptions, 'forwardArgs' | 'cap
    * resolves before the timer can fire).
    */
   timeoutMs?: number
+  /**
+   * Spawn it with fd 3 as its signal channel and route its polite signals
+   * there (`signalThrough`): a Linux sandboxed command, whose group signal
+   * would kill bwrap instead (`wrapSandboxedCommand`'s `forwardsSignals`).
+   */
+  signalChannel?: boolean
 }
 
 /**
@@ -283,18 +368,38 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
 
   let child: ReturnType<typeof Bun.spawn>
   try {
-    child = Bun.spawn(['sh', '-c', execWrap(opts.command)], {
-      cwd: opts.cwd,
-      env: opts.env as Record<string, string>,
-      stdin: 'ignore',
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
+    child = spawnGuarded(() =>
+      Bun.spawn([executablePath('sh'), '-c', execWrap(opts.command)], {
+        argv0: 'sh',
+        cwd: opts.cwd,
+        env: opts.env as Record<string, string>,
+        // A pipe vx holds and never writes: stdin stays open while vx
+        // lives and ends when it does. A dev server that exits on stdin
+        // EOF (esbuild --watch, Vite's case in turborepo#8915) became ready
+        // and exited 0 under 'ignore'. Not the terminal: several servers
+        // would steal each other's keystrokes, and a CI's /dev/null stdin
+        // is the same EOF. The one-shot spawn below keeps 'ignore', so a
+        // task that reads stdin can never hang CI.
+        stdio:
+          opts.signalChannel === true ? ['pipe', 'pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'],
+        // Its own session and process group, so a kill reaches what it
+        // forked (kill-tree.ts). stdin is a pipe, so a background group
+        // never stops on a terminal read.
+        detached: true,
+      }),
+    )
+    if (opts.signalChannel === true) {
+      signalThrough(child, child.stdio[3] as number)
+      const spawned = child
+      void spawned.exited.then(() => closeSignalChannel(spawned))
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     return {
       child: undefined as unknown as ReturnType<typeof Bun.spawn>,
-      ready: Promise.reject(new Error(`failed to spawn persistent task: ${message}`)),
+      ready: Promise.reject(
+        new PersistentReadyError(`failed to spawn persistent task: ${message}`, 'spawn'),
+      ),
       readyMs: () => Date.now() - start,
     }
   }
@@ -389,12 +494,26 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
     readyTimer = setTimeout(() => {
       if (readyAt === undefined) {
         rejectReady(
-          new Error(
+          new PersistentReadyError(
             `persistent task not ready within ${opts.timeoutMs}ms — ` +
               `readyWhen pattern never matched; child killed`,
+            'timeout',
           ),
         )
-        child.kill('SIGTERM')
+        // Listed on the group guard until the SIGKILL: the shell may die
+        // on the SIGTERM and let the group go while the server runs out
+        // the grace, and a vx that exits inside it (the timer is unref'd)
+        // leaves the server to the guard (kill-tree.ts, item 865).
+        const letGo = holdGroups([child])
+        killTree(child, 'SIGTERM')
+        // Same escalation as `armTimeout`: a server that traps TERM and
+        // never became ready is not in the persistent registry, so nothing
+        // else would ever kill it — it outlived the run under init.
+        const killTimer = setTimeout(() => {
+          killTree(child, 'SIGKILL')
+          letGo()
+        }, killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
+        killTimer.unref?.()
       }
     }, opts.timeoutMs)
   }
@@ -403,12 +522,16 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   // — reject the ready promise so the caller can surface it.
   void child.exited.then((code) => {
     opts.liveChildren?.delete(child)
+    markGroupIfGone(child)
+    releaseGroup(child)
     if (readyTimer !== undefined) clearTimeout(readyTimer)
     if (readyAt === undefined) {
       rejectReady(
-        new Error(
+        new PersistentReadyError(
           `persistent task exited before becoming ready (exit ${code ?? '?'})` +
             (readyRe ? ` — readyWhen pattern never matched` : ''),
+          'exited',
+          code ?? undefined,
         ),
       )
     }
@@ -425,6 +548,22 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   }
 }
 
+/**
+ * What a task's frame says when `Bun.spawn` itself threw. The text goes
+ * through `onStderr` AND onto the result: the orchestrator retains no
+ * stderr (execute-task's capture), so a reason that only sat on the result
+ * reached nobody — a box without `sh` showed "failed (exit 127)" under a
+ * bare `$ <command>` and nothing else (2026-09-16). An ENOENT with the
+ * working directory in place is the shell; Bun's own text names the rest.
+ */
+export function spawnFailureText(err: unknown, cwd: string, what = 'task'): string {
+  if (isExecutableMissing(err) && existsSync(cwd)) {
+    return `\n[vx] vx runs each task with sh -c: failed to spawn 'sh' (working dir: ${cwd}). Install a POSIX sh and re-run.\n`
+  }
+  const message = err instanceof Error ? err.message : String(err)
+  return `\n[vx] failed to spawn ${what}: ${message}\n`
+}
+
 export async function runCommand(opts: RunOptions): Promise<RunResult> {
   const start = Date.now()
   const fullCommand =
@@ -434,21 +573,24 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
 
   let proc: ReturnType<typeof Bun.spawn>
   try {
-    proc = Bun.spawn(['sh', '-c', execWrap(fullCommand)], {
-      cwd: opts.cwd,
-      env: opts.env as Record<string, string>,
-      stdin: 'ignore',
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
+    proc = spawnGuarded(() =>
+      Bun.spawn([executablePath('sh'), '-c', execWrap(fullCommand)], {
+        argv0: 'sh',
+        cwd: opts.cwd,
+        env: opts.env as Record<string, string>,
+        stdin: 'ignore',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        // Its own session and process group, so a kill reaches what it
+        // forked (kill-tree.ts). stdin is ignored, so a background group
+        // never stops on a terminal read.
+        detached: true,
+      }),
+    )
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err)
-    return {
-      exitCode: 127,
-      durationMs: Date.now() - start,
-      stdout: '',
-      stderr: `\n[vx] failed to spawn: ${message}\n`,
-    }
+    const stderr = spawnFailureText(err, opts.cwd)
+    opts.onStderr?.(stderr)
+    return { exitCode: 127, durationMs: Date.now() - start, stdout: '', stderr }
   }
 
   opts.liveChildren?.add(proc)
@@ -465,11 +607,15 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   // lets a clean exit EOF immediately and only cuts off a stuck reader after a
   // brief grace — without this the run hangs forever.
   await proc.exited
-  timeout.clear()
+  await timeout.settle()
+  let cut = false
   if (timeout.timedOut()) ac.abort()
-  else await drainOrAbort(streams, ac)
-  const [stdout, stderr] = await streams
+  else cut = await drainOrAbort(streams, ac)
+  const [stdout, streamed] = await streams
+  if (cut) opts.onStderr?.(POST_EXIT_CUT_LINE)
+  const stderr = cut ? streamed + POST_EXIT_CUT_LINE : streamed
   opts.liveChildren?.delete(proc)
+  releaseGroup(proc)
   const exitCode = proc.exitCode ?? (proc.signalCode ? signalExitCode(proc.signalCode) : 1)
   return {
     exitCode,
@@ -478,7 +624,100 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
     stderr,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
-    ...resourceUsageToCpuRss(proc.resourceUsage()),
+    ...resourceUsageToCpuRss(proc.resourceUsage(), ownRssHighWater()),
+  }
+}
+
+/**
+ * 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
+ * forking parent's high-water mark into the child's figure at exec (a
+ * forked child starts with its parent's pages; `exec_mmap` keeps the old
+ * mm's peak), so a task lighter than vx itself reads vx's footprint —
+ * `true` read 44 MB through vx while its shell's `VmHWM` was 1.9 MB, and
+ * 300 MB allocated in the parent made `true` read 328 MB (2026-09-12).
+ * Read after the child exits so it covers the whole task's span (the mark
+ * is monotonic). Linux reads `VmHWM`; elsewhere the current RSS is the
+ * bound in hand.
+ */
+export function ownRssHighWater(): number {
+  if (process.platform === 'linux') {
+    try {
+      const m = /VmHWM:\s+(\d+) kB/.exec(readFileSync('/proc/self/status', 'utf8'))
+      if (m !== null) return Number(m[1]) * 1024
+    } catch {
+      // /proc unreadable: fall through to the current RSS.
+    }
+  }
+  return process.memoryUsage.rss()
+}
+
+/**
+ * What a task's captured output keeps: the first `CAPTURE_HEAD_CHARS` and
+ * the last `CAPTURE_TAIL_CHARS` characters, the dropped middle counted and
+ * named where it was. The live stream is never bounded — every byte still
+ * reaches the terminal as the task writes it — only the copy vx retains
+ * for the cache entry and its replay. Unbounded, a task printing 200 MB
+ * cost vx 620 MB of RSS on the miss AND on every hit, and its stdout sat
+ * whole in `cache.db` (measured 2026-09-16); a realistic chatty suite is
+ * 5–20 MB, so the bound is above what a replay is worth reading anyway.
+ */
+export const CAPTURE_HEAD_CHARS = 8 * 1024 * 1024
+export const CAPTURE_TAIL_CHARS = 8 * 1024 * 1024
+
+const mib = (n: number): string => `${(n / (1024 * 1024)).toFixed(1)} MiB`
+
+/** The line that stands where the dropped middle was. */
+export function droppedOutputLine(dropped: number): string {
+  return (
+    `\n[vx] ${mib(dropped)} of output not kept — vx keeps the first ${mib(CAPTURE_HEAD_CHARS)} ` +
+    `and the last ${mib(CAPTURE_TAIL_CHARS)} of a task's output for its cache entry and replay\n`
+  )
+}
+
+/**
+ * A head-and-tail accumulator: the head fills once, the tail is a ring
+ * of chunks trimmed from the front, so memory is bounded by the two
+ * limits plus one chunk whatever the task prints.
+ */
+class BoundedCapture {
+  private head = ''
+  private readonly tail: string[] = []
+  private tailLen = 0
+  private dropped = 0
+
+  push(chunk: string): void {
+    if (this.head.length < CAPTURE_HEAD_CHARS) {
+      const room = CAPTURE_HEAD_CHARS - this.head.length
+      if (chunk.length <= room) {
+        this.head += chunk
+        return
+      }
+      this.head += chunk.slice(0, room)
+      chunk = chunk.slice(room)
+    }
+    this.tail.push(chunk)
+    this.tailLen += chunk.length
+    while (this.tailLen > CAPTURE_TAIL_CHARS) {
+      const first = this.tail[0]!
+      const excess = this.tailLen - CAPTURE_TAIL_CHARS
+      if (first.length <= excess) {
+        this.tail.shift()
+        this.tailLen -= first.length
+        this.dropped += first.length
+      } else {
+        this.tail[0] = first.slice(excess)
+        this.tailLen -= excess
+        this.dropped += excess
+      }
+    }
+  }
+
+  text(): string {
+    const tail = this.tail.join('')
+    return this.dropped === 0
+      ? this.head + tail
+      : this.head + droppedOutputLine(this.dropped) + tail
   }
 }
 
@@ -501,7 +740,7 @@ export async function streamToString(
   // so the runtime value is always a ReadableStream; the `number` branch
   // is unreachable but typed.
   if (!stream || typeof stream === 'number') return ''
-  let full = ''
+  const full = new BoundedCapture()
   const reader = stream.getReader()
   const decoder = new TextDecoder()
   // On abort, cancel the read so a pending `reader.read()` resolves
@@ -517,19 +756,63 @@ export async function streamToString(
       const { value, done } = await reader.read()
       if (done) break
       const chunk = decoder.decode(value, { stream: true })
-      if (retain) full += chunk
+      if (retain) full.push(chunk)
       onChunk?.(chunk)
     }
     const tail = decoder.decode()
     if (tail.length > 0) {
-      if (retain) full += tail
+      if (retain) full.push(tail)
       onChunk?.(tail)
     }
   } finally {
     signal?.removeEventListener('abort', onAbort)
     reader.releaseLock()
   }
-  return full
+  return full.text()
+}
+
+/**
+ * How far above the parent's own mark a child's `ru_maxrss` must read to
+ * count as the child's. A light child inherits the parent's footprint at
+ * exec, so its reading sits ON the floor by construction, and the kernel's
+ * per-thread RSS counters lag by up to 64 pages between syncs — a `true`
+ * spawned from a 300 MB parent read 376 MB against a floor a few pages
+ * lower on one CI run in twelve (2026-09-16). Four MiB is above any
+ * accounting jitter and below what any reservation resolves (64 MB steps).
+ */
+export const RSS_FLOOR_SLACK_BYTES = 4 * 1024 * 1024
+
+const MIN_PLAUSIBLE_PEAK_BYTES = 1024 * 1024
+
+/**
+ * A child's `maxRSS` in BYTES, whatever unit the runtime reported it in.
+ *
+ * Bun >= 1.4 — vx's declared floor — normalizes the kernel's `ru_maxrss`
+ * (kilobytes on Linux, bytes on macOS) before handing it over, and this file
+ * used to state that as "BYTES on every platform". It is not true of every
+ * Bun: 1.3.11 passes the raw kilobytes through, so every peak read 1024×
+ * SMALL, fell under the parent floor and recorded nothing. The opposite
+ * mistake is in this file's own history — an unconditional ×1024 on Linux
+ * made a 64 MB suite read as 64 GB and, once reservations were learned from
+ * that history, ran every task alone (2026-09-12). Both directions come from
+ * asserting a platform unit instead of deciding it from the number in hand.
+ *
+ * The number decides it. No process peaks under a megabyte — a bare `true`
+ * costs a couple — so a reading below that is not bytes, it is the kernel's
+ * kilobytes, and multiplying is right by the same margin that makes the test
+ * safe. A real byte figure is never near the threshold, and neither is a real
+ * kilobyte one: the two live 1024× apart.
+ *
+ * Calibrating against this process's OWN `process.resourceUsage()` was the
+ * first attempt and it was wrong: that is the node-compatible API, which
+ * reports kilobytes even where `Subprocess.resourceUsage()` reports bytes, so
+ * the ratio read 1024 on a runtime already handing over bytes and doubled the
+ * old 64 GB defect. It passed here, where both APIs use kilobytes, and turned
+ * CI red on both platforms (2026-09-20). Compare like with like, or do not
+ * compare at all.
+ */
+export function peakRssBytes(maxRSS: number): number {
+  return maxRSS > 0 && maxRSS < MIN_PLAUSIBLE_PEAK_BYTES ? maxRSS * 1024 : maxRSS
 }
 
 /**
@@ -540,18 +823,19 @@ export async function streamToString(
  */
 export function resourceUsageToCpuRss(
   usage: ReturnType<ReturnType<typeof Bun.spawn>['resourceUsage']>,
-  platform: NodeJS.Platform = process.platform,
+  /** The parent's own high-water mark (`ownRssHighWater`); a peak at or under it is inherited, not the child's, and is not reported. */
+  floorBytes = 0,
 ): { cpuMs?: number; peakRssBytes?: number } {
   if (!usage) return {}
   // cpuTime.total is microseconds as a bigint → ms.
   const cpuMs = Number(usage.cpuTime.total) / 1000
-  // maxRSS is the raw kernel `ru_maxrss`, whose UNIT IS PLATFORM-SPECIFIC and
-  // Bun does NOT normalize it:
-  //   • Linux   → kilobytes  (multiply by 1024 for bytes)
-  //   • macOS / BSD → bytes  (already bytes; do NOT multiply)
-  //   • Windows → bytes (PeakWorkingSetSize)
-  // Treating macOS's byte value as KB inflates peak RSS by 1024× — e.g. a
-  // real 460 MB showed up as 460 GB. Convert per platform.
-  const peakRssBytes = platform === 'linux' ? usage.maxRSS * 1024 : usage.maxRSS
-  return { cpuMs, peakRssBytes }
+  // `maxRSS` in whatever unit this runtime reports, in bytes by the rule
+  // above. `tests/runner.test.ts` allocates a known number of bytes and
+  // reads the peak back within a bounded factor of it, which is the
+  // end-to-end check on both the unit and the floor.
+  // A reading at or within the slack of the parent's own mark is the
+  // parent's (see `ownRssHighWater`, `RSS_FLOOR_SLACK_BYTES`): the child's
+  // peak is unknown, bounded by it.
+  const peak = peakRssBytes(usage.maxRSS)
+  return peak > floorBytes + RSS_FLOOR_SLACK_BYTES ? { cpuMs, peakRssBytes: peak } : { cpuMs }
 }