@vzn/vx 0.0.16 → 0.0.21

package/src/exec/executor.ts

@@ -0,0 +1,224 @@
+// The per-task execution contract. `execute-task.ts` decides WHAT to run
+// (command, env, sandbox baselines, capture) and hands a fully-resolved
+// request here; an executor decides WHERE/HOW the process runs. Core's own
+// `local-executor.ts` is the in-process spawn, and it sits at the TAIL of
+// every executor list — what a plugin executor declines runs here.
+// Persistent tasks (`exec.persistent`) never reach an executor: they are local by
+// construction (a worker cannot hand the submitter a listening port) and
+// stay on `runPersistent`.
+//
+// Lives in `exec/` (not `orchestrator/`) so the contract depends only on
+// process primitives — the module-boundary matrix forbids `exec` → `cache`,
+// which is why sandbox baselines arrive pre-resolved on the request.
+
+import type { CaptureConfig, RunResult } from './runner.js'
+import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
+
+/** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
+export interface ExecuteSandbox {
+  readonly baseAllowRead: readonly string[]
+  readonly baseAllowWrite: readonly string[]
+  readonly baseDenyRead: readonly string[]
+  /**
+   * Only denials on a path under this directory are reported. A denial
+   * outside it is still ENFORCED — the task cannot leave its project — but
+   * that is the wall doing its job, not a finding to fail a run over.
+   */
+  readonly reportWithin: string
+  readonly config: ResolvedSandboxConfig
+}
+
+/** One declared input file, as the cache key saw it. */
+export interface InputFile {
+  /** Workspace-relative POSIX path. */
+  readonly path: string
+  /** Git blob OID of the WORKTREE bytes — for a symlink, of its target string — the same digest the key folds. */
+  readonly digest: string
+}
+
+/**
+ * Everything the cache key folds for one task, with values — the set a
+ * remote executor needs to reproduce the task somewhere else. Built on the
+ * miss path only, from the same resolution that produced the key, so it can
+ * never drift from what a hit would have matched. Held in memory for the
+ * attempt and never persisted: `env` values and `runtime` output may be
+ * secrets (cache.db stores only their digests).
+ */
+export interface TaskInputs {
+  /** Declared `cache.inputs.files` + `workspaceFiles` (own outputs excluded), sorted by path. */
+  readonly files: readonly InputFile[]
+  /** Declared `cache.inputs.env` names with their resolved values. */
+  readonly env: ReadonlyArray<{ readonly name: string; readonly value: string }>
+  /** `cache.inputs.runtime` commands and the output that was folded — a toolchain expectation. */
+  readonly runtime: ReadonlyArray<{ readonly command: string; readonly output: string }>
+  /** `cache.inputs.workspaceRuntime`, same shape. */
+  readonly workspaceRuntime: ReadonlyArray<{ readonly command: string; readonly output: string }>
+  /**
+   * Dependencies whose cache keys are folded. `outputs` lists each one's
+   * declared output files (workspace-relative POSIX, as stored with its cache
+   * entry) — restored on disk before this task runs, so an input-shipping
+   * executor can include them in the input root. Empty when the upstream's
+   * entry is not in the local index (a non-cacheable dependency).
+   */
+  readonly upstream: ReadonlyArray<{
+    readonly taskId: string
+    readonly hash: string
+    readonly outputs: readonly string[]
+  }>
+  /** Digest of the project's own `package.json` (folded even when no glob lists it). */
+  readonly packageJsonDigest: string
+  /** Digest of the resolved task config. */
+  readonly configDigest: string
+  /** The workspace fingerprint (root manifests + lockfile). */
+  readonly workspaceFingerprint: string
+}
+
+export interface ExecuteRequest {
+  /** `${project}#${task}` — for executors that route or log by task. */
+  readonly taskId: string
+  readonly workspaceRoot: string
+  /** Present for cacheable tasks (the miss path); absent when the task declares no `cache`. */
+  readonly inputs?: TaskInputs
+  /**
+   * The task's cache key (present when the task is cacheable). An executor
+   * that keeps its own remote record of executions — so a dependent's input
+   * tree can reference this task's outputs without the bytes ever landing on
+   * this machine — needs a stable address, and the key is that address.
+   */
+  readonly cacheKey?: string
+  /**
+   * Cache READS are disabled for this run (`--force` / `--no-cache`). An
+   * executor that keeps its OWN remote record of executions must not serve
+   * this request from it — the user asked for re-execution, and a private
+   * cache that ignores the flag is still a cache.
+   */
+  readonly refresh?: boolean
+  /**
+   * `exec.remote: 'only'`: the task produces a REMOTE input tree. The
+   * executor should not materialise outputs onto this machine's disk, and
+   * may satisfy the request from its own remote record of a previous
+   * execution under the same key.
+   */
+  readonly remoteOnly?: boolean
+  /**
+   * Whether this task's outputs must land on the submitter's disk now.
+   * 'eager' (or absent) = materialise as today. 'deferred' = leave them
+   * in the remote store and return `outputs: {kind:'deferred'}` with a
+   * closure core can call if a local consumer turns out to need them.
+   * A local executor ignores this — it writes in place by construction.
+   */
+  readonly download?: 'eager' | 'deferred'
+  /** The declared output globs — project-relative `files`, root-relative `workspaceFiles`. */
+  readonly outputs: {
+    readonly files: readonly string[]
+    readonly workspaceFiles: readonly string[]
+  }
+  readonly command: string
+  /** Appended to `command`, shell-quoted, by the executor (forwarded CLI args). */
+  readonly forwardArgs: readonly string[]
+  readonly cwd: string
+  readonly env: NodeJS.ProcessEnv
+  /**
+   * `exec.env.define` verbatim — literal name=value pairs from the task
+   * config. `env` above is the fully RESOLVED child environment and is
+   * host-specific (it carries this machine's PATH, HOME, TMPDIR…), so an
+   * executor that ships the environment somewhere else cannot use it: those
+   * values would enter the action identity and split every machine from
+   * every other. These are declared in the config, so they are the same
+   * everywhere and safe to forward.
+   */
+  readonly envDefine: Readonly<Record<string, string>>
+  readonly capture: CaptureConfig
+  readonly timeoutMs?: number
+  readonly onStdout: (chunk: string) => void
+  readonly onStderr: (chunk: string) => void
+  /** See `RunOptions.liveChildren`: the run's SIGINT/SIGTERM registry. */
+  readonly liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  readonly sandbox?: ExecuteSandbox
+}
+
+export interface ExecuteResult extends RunResult {
+  /** Sandbox violations (empty when unsandboxed). */
+  readonly violations: readonly SandboxViolation[]
+  /**
+   * Where this task's outputs are. Absent = `{kind:'disk'}` — in place
+   * under `cwd`, which is what every executor did before deferral
+   * existed. `deferred` means they are NOT on disk and `materialize()`
+   * fetches them; core calls it lazily, at most once, and then saves an
+   * ordinary cache entry, so a deferred task leaves no permanent third
+   * state behind.
+   */
+  readonly outputs?: { kind: 'disk' } | { kind: 'deferred'; materialize: () => Promise<void> }
+  /**
+   * Executor-reported placement label — which machine ran the command
+   * (a REAPI worker id, a pool member). Absent = this host. Rides
+   * `TaskOutcome.where` into telemetry so a task can be attributed to
+   * its worker; never persisted to the analytics store.
+   */
+  readonly where?: string
+}
+
+/** What an executor sees when a task is PLACED — once per task, before scheduling. */
+export interface TaskPlacement {
+  readonly taskId: string
+  readonly projectName: string
+  readonly projectDir: string
+  readonly command: string
+  /**
+   * Must run on this machine: the task is persistent, depends (transitively)
+   * on a persistent task, or declares `exec.remote: false`. A `remote`
+   * executor is never offered such a task.
+   */
+  readonly pinnedLocal: boolean
+  /** Declares `cache` — the only tasks whose input set is described, and so the only ones that can ship. */
+  readonly cacheable: boolean
+}
+
+export interface TaskExecutor {
+  /** Shown in errors; `'local'` for core's own. */
+  readonly name: string
+  /** Runs the command somewhere else. Never offered a `pinnedLocal` task. */
+  readonly remote?: boolean
+  /**
+   * How many tasks this executor runs at once. Its tasks then occupy a pool
+   * of this size instead of the local worker slots, so a remote pool is not
+   * throttled by the local CPU count. Absent = the local pool.
+   */
+  readonly capacity?: number
+  /** Per-task opt-out at placement time. Absent = accepts every task it is offered. */
+  accepts?(task: TaskPlacement): boolean
+  /**
+   * The tasks placed here that have NOT finished yet — called once after
+   * placement with the whole set, then again after each completion (any
+   * outcome: a cache hit and a failure both remove one).
+   *
+   * An executor that provisions something per task — a container, an
+   * allocation, a pod — otherwise has to guess. `capacity` says how much it
+   * MAY run at once; this says how much is actually left, so it can size
+   * what it creates to the work that remains and give capacity back the
+   * moment the run can no longer use it, rather than holding it until
+   * teardown. Absent = the executor does not care and nothing is computed
+   * for it.
+   */
+  demand?(remaining: ReadonlySet<string>): void
+  execute(req: ExecuteRequest): Promise<ExecuteResult>
+}
+
+/**
+ * Place one task: the first executor, in declaration order, that may take
+ * it — a `remote` executor is skipped for a `pinnedLocal` task, then
+ * `accepts()` decides. Decided once per task before scheduling. The local
+ * executor accepts everything, so with it declared this cannot throw.
+ */
+export function selectExecutor(
+  executors: readonly TaskExecutor[],
+  task: TaskPlacement,
+): TaskExecutor {
+  for (const executor of executors) {
+    if (task.pinnedLocal && executor.remote === true) continue
+    if (executor.accepts === undefined || executor.accepts(task)) return executor
+  }
+  throw new Error(
+    `no executor accepted ${task.taskId} (declared: ${executors.map((e) => e.name).join(', ')}). Core's local executor accepts every task, so this means it is missing from the list.`,
+  )
+}

package/src/exec/index.ts

@@ -1,13 +1,35 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { buildIsolatedEnv } from './env.js'
-export { runCommand, runPersistent, signalExitCode } from './runner.js'
+export { buildIsolatedEnv, VX_RUN_TASK_ENV, VX_RUN_WORKSPACE_ENV } from './env.js'
+export {
+  runCommand,
+  runPersistent,
+  shellQuote,
+  signalExitCode,
+  type CaptureConfig,
+} from './runner.js'
 export {
   initSandbox,
   probeSandbox,
+  unavailableReason,
   resetSandbox,
   resolveSandboxConfig,
   runSandboxed,
+  releaseBridges,
+  wrapSandboxedCommand,
+  type ResolvedSandboxConfig,
   type SandboxViolation,
 } from './sandbox-runtime.js'
+export { type DeniedCall } from './sandbox-violations.js'
+export { localExecutor } from './local-executor.js'
+export {
+  selectExecutor,
+  type ExecuteRequest,
+  type ExecuteResult,
+  type ExecuteSandbox,
+  type InputFile,
+  type TaskExecutor,
+  type TaskInputs,
+  type TaskPlacement,
+} from './executor.js'

package/src/exec/local-executor.ts

@@ -0,0 +1,41 @@
+// Core's own local executor: spawn the task's command here, in this
+// process. Not a plugin — "run it on this machine" is not a capability
+// someone else supplies differently, it is what running MEANS when no
+// plugin claims the task, so it sits at the TAIL of every executor list
+// (owner, 2026-09-05). An executor plugin places work ELSEWHERE; its
+// absence is "here".
+import { runCommand } from './runner.js'
+import { runSandboxed } from './sandbox-runtime.js'
+import type { TaskExecutor } from './executor.js'
+
+/** The local executor. Accepts every task. */
+export function localExecutor(): TaskExecutor {
+  return {
+    name: 'local',
+    async execute(req) {
+      const common = {
+        command: req.command,
+        cwd: req.cwd,
+        env: req.env,
+        forwardArgs: req.forwardArgs,
+        onStdout: req.onStdout,
+        onStderr: req.onStderr,
+        capture: req.capture,
+        ...(req.liveChildren !== undefined ? { liveChildren: req.liveChildren } : {}),
+        ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+      }
+      if (req.sandbox === undefined) {
+        const res = await runCommand(common)
+        return { ...res, violations: [] }
+      }
+      return runSandboxed({
+        ...common,
+        baseAllowRead: req.sandbox.baseAllowRead,
+        baseAllowWrite: req.sandbox.baseAllowWrite,
+        baseDenyRead: req.sandbox.baseDenyRead,
+        reportWithin: req.sandbox.reportWithin,
+        config: req.sandbox.config,
+      })
+    },
+  }
+}

package/src/exec/runner.ts

@@ -4,7 +4,9 @@
 // process exits. cpuMs / peakRssBytes are then surfaced on RunResult and
 // folded into the v11 `runs` table by the orchestrator.
 
+import { readFileSync } from 'node:fs'
 import { constants as osConstants } from 'node:os'
+import { killGraceMs } from '../util/index.js'
 
 export interface RunResult {
   exitCode: number
@@ -25,6 +27,20 @@ export interface RunResult {
   peakRssBytes?: number
 }
 
+/**
+ * Which streams `runCommand` retains into `RunResult.stdout` / `.stderr`.
+ * Both default to true — the primitive's contract is that those fields hold
+ * what the child wrote, and a field that silently lies is worse than one
+ * that costs. A caller that will not READ a stream opts down here: the live
+ * `onStdout` / `onStderr` callbacks still fire for every chunk, so only the
+ * retained string is dropped. Retaining a stream nothing reads costs its
+ * full byte size in heap, for the whole task.
+ */
+export interface CaptureConfig {
+  stdout?: boolean
+  stderr?: boolean
+}
+
 export interface RunOptions {
   command: string
   cwd: string
@@ -34,6 +50,8 @@ export interface RunOptions {
   /** Called for each chunk of stdout/stderr as it arrives, for live output. */
   onStdout?: (chunk: string) => void
   onStderr?: (chunk: string) => void
+  /** See `CaptureConfig`. Omitted → both streams retained (today's behaviour). */
+  capture?: CaptureConfig
   /**
    * Upper bound (ms) on the child's run time. When it elapses the
    * child is SIGTERMed and the result is flagged `timedOut`. Undefined
@@ -136,6 +154,12 @@ export function signalExitCode(signal: string): number {
   return num === undefined ? 130 : 128 + num
 }
 
+/**
+ * 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
@@ -150,13 +174,67 @@ export function armTimeout(
 ): { timedOut: () => boolean; clear: () => void } {
   if (timeoutMs === undefined) return { timedOut: () => false, clear: () => {} }
   let fired = false
+  let killTimer: ReturnType<typeof setTimeout> | undefined
   const timer = setTimeout(() => {
     fired = true
     proc.kill('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'), killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
+    killTimer.unref?.()
   }, timeoutMs)
-  return { timedOut: () => fired, clear: () => clearTimeout(timer) }
+  return {
+    timedOut: () => fired,
+    clear: () => {
+      clearTimeout(timer)
+      if (killTimer !== undefined) clearTimeout(killTimer)
+    },
+  }
 }
 
+/**
+ * Grace after the direct child exits before we abort the stdout/stderr readers.
+ * The pipe reaches EOF only when EVERY write-end fd is closed, so a task that
+ * backgrounds a process inheriting fd 1/2 (`server & echo up` — `execWrap`
+ * leaves compound commands as `sh -c`, so `sh` exits while the grandchild holds
+ * the pipe) never EOFs. On a clean exit with no lingering writer the pipe EOFs
+ * 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.
+ */
+const POST_EXIT_DRAIN_MS = 250
+
+/**
+ * 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).
+ */
+export async function drainOrAbort(streams: Promise<unknown>, ac: AbortController): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), POST_EXIT_DRAIN_MS)
+    timer.unref?.()
+  })
+  const winner = await Promise.race([streams.then(() => 'drained' as const), deadline])
+  if (timer !== undefined) clearTimeout(timer)
+  if (winner === 'timeout') ac.abort()
+}
+
+/**
+ * Upper bound on the text a `readyWhen` regex is tested against. The matcher
+ * normally keeps only the trailing partial line, so this bites only when the
+ * stream has no line breaks at all.
+ */
+const READY_MATCH_WINDOW_CHARS = 64 * 1024
+
 export interface PersistentSpawn {
   /** Underlying Bun subprocess so the orchestrator can SIGTERM it later. */
   child: ReturnType<typeof Bun.spawn>
@@ -167,14 +245,15 @@ export interface PersistentSpawn {
    * Rejects with the spawn error if the child fails to start.
    */
   ready: Promise<void>
-  /** Captured stdout/stderr up to the moment ready resolved. */
-  bufferedStdout: () => string
-  bufferedStderr: () => string
   /** ms elapsed from spawn to ready (or to current time if not yet ready). */
   readyMs: () => number
 }
 
-export interface PersistentOptions extends Omit<RunOptions, 'forwardArgs'> {
+// `capture` is a `runCommand` concept: a persistent task never returns a
+// RunResult (it is handed back at READY, still running), so there is no
+// retained string to opt out of. Its output reaches the caller only through
+// the live callbacks.
+export interface PersistentOptions extends Omit<RunOptions, 'forwardArgs' | 'capture'> {
   /**
    * String regex. The first stdout/stderr line that matches signals
    * "ready". Undefined → ready immediately on spawn.
@@ -198,8 +277,6 @@ export interface PersistentOptions extends Omit<RunOptions, 'forwardArgs'> {
  */
 export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   const start = Date.now()
-  let bufferedStdout = ''
-  let bufferedStderr = ''
   let readyAt: number | undefined
 
   // Pattern compiled once; thrown errors surface synchronously so the
@@ -220,8 +297,6 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
     return {
       child: undefined as unknown as ReturnType<typeof Bun.spawn>,
       ready: Promise.reject(new Error(`failed to spawn persistent task: ${message}`)),
-      bufferedStdout: () => '',
-      bufferedStderr: () => `\n[vx] failed to spawn: ${message}\n`,
       readyMs: () => Date.now() - start,
     }
   }
@@ -255,16 +330,13 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
     let fragment = ''
     const handleChunk = (chunk: string): void => {
       if (chunk.length === 0) return
-      // Buffers capture "up to the moment ready resolved" (their
-      // documented contract) — a dev server kept alive for hours must
-      // not accrete its whole log history into vx's heap.
-      if (isStderr) {
-        if (readyAt === undefined) bufferedStderr += chunk
-        opts.onStderr?.(chunk)
-      } else {
-        if (readyAt === undefined) bufferedStdout += chunk
-        opts.onStdout?.(chunk)
-      }
+      // Chunks are forwarded, never retained. The one consumer of a
+      // persistent task's text is the logger, which keeps its OWN bounded
+      // tail fed from these same callbacks (registered at taskStart, so it
+      // covers the pre-ready window too) — a second copy here was read by
+      // nobody.
+      if (isStderr) opts.onStderr?.(chunk)
+      else opts.onStdout?.(chunk)
       if (readyRe && readyAt === undefined) {
         fragment += chunk
         if (readyRe.test(fragment)) {
@@ -273,6 +345,17 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
         } else {
           const lastNl = fragment.lastIndexOf('\n')
           if (lastNl >= 0) fragment = fragment.slice(lastNl + 1)
+          // Dropping complete lines assumes the stream HAS line breaks.
+          // `\r`-only output — a progress bar, a spinner — is one endless
+          // line, so the trim above never fires and the fragment becomes a
+          // third unbounded accumulator (measured 464 MiB in 6 s, and the
+          // per-chunk `test` over an ever-growing string makes it quadratic
+          // in CPU too). Keep the most RECENT window: a match may span the
+          // chunk boundary, and no readiness marker is anywhere near this
+          // long.
+          if (fragment.length > READY_MATCH_WINDOW_CHARS) {
+            fragment = fragment.slice(fragment.length - READY_MATCH_WINDOW_CHARS)
+          }
         }
       }
     }
@@ -314,6 +397,14 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
           ),
         )
         child.kill('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(
+          () => child.kill('SIGKILL'),
+          killGraceMs(TIMEOUT_SIGKILL_GRACE_MS),
+        )
+        killTimer.unref?.()
       }
     }, opts.timeoutMs)
   }
@@ -340,8 +431,6 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   return {
     child,
     ready,
-    bufferedStdout: () => bufferedStdout,
-    bufferedStderr: () => bufferedStderr,
     readyMs: () => (readyAt ?? Date.now()) - start,
   }
 }
@@ -376,15 +465,19 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   const timeout = armTimeout(proc, opts.timeoutMs)
   const ac = new AbortController()
   const streams = Promise.all([
-    streamToString(proc.stdout, opts.onStdout, ac.signal),
-    streamToString(proc.stderr, opts.onStderr, ac.signal),
+    streamToString(proc.stdout, opts.onStdout, ac.signal, opts.capture?.stdout ?? true),
+    streamToString(proc.stderr, opts.onStderr, ac.signal, opts.capture?.stderr ?? true),
   ])
-  // Gate on the child's own exit, not on stream EOF: a timeout SIGTERM
-  // kills `sh` but an orphaned grandchild can keep the pipe open, so we
-  // abort the readers once the child is gone rather than wait forever.
+  // Gate on the child's own exit, not on stream EOF: an orphaned grandchild
+  // can keep the pipe open past the child's exit (a timeout SIGTERM leaves the
+  // grandchild alive; a NORMAL exit of `server & echo up` does too), so EOF may
+  // never arrive. A timeout aborts the readers at once; otherwise drainOrAbort
+  // 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()
   if (timeout.timedOut()) ac.abort()
+  else await drainOrAbort(streams, ac)
   const [stdout, stderr] = await streams
   opts.liveChildren?.delete(proc)
   const exitCode = proc.exitCode ?? (proc.signalCode ? signalExitCode(proc.signalCode) : 1)
@@ -395,18 +488,46 @@ 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()
 }
 
 /**
  * Drain a `Bun.spawn` stdout/stderr stream while invoking the live
- * callback per UTF-8 chunk. Returns the full accumulated string.
+ * callback per UTF-8 chunk. Returns the accumulated string, or `''` when
+ * `retain` is false — the stream is still fully drained and every chunk
+ * still reaches `onChunk`; only the retained copy is dropped, so a caller
+ * that will not read it does not pay its byte size in heap.
  */
 export async function streamToString(
   stream: ReadableStream<Uint8Array> | number | undefined,
   onChunk?: (s: string) => void,
   signal?: AbortSignal,
+  retain = true,
 ): Promise<string> {
   // Bun.spawn types stdout/stderr as `ReadableStream | number | undefined`
   // — the `number` is for inheritance modes, only present when the caller
@@ -430,12 +551,12 @@ export async function streamToString(
       const { value, done } = await reader.read()
       if (done) break
       const chunk = decoder.decode(value, { stream: true })
-      full += chunk
+      if (retain) full += chunk
       onChunk?.(chunk)
     }
     const tail = decoder.decode()
     if (tail.length > 0) {
-      full += tail
+      if (retain) full += tail
       onChunk?.(tail)
     }
   } finally {
@@ -453,18 +574,23 @@ 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` is BYTES on every platform: Bun normalizes the kernel's
+  // `ru_maxrss` (kilobytes on Linux, bytes on macOS) before handing it
+  // over, as its typing says. This used to multiply by 1024 on Linux on
+  // the belief that Bun passed the raw value through, and every Linux
+  // peak was 1024× too big — a 64 MB `bun test` recorded as 64 GB in
+  // telemetry, `--summarize` and the run history, and once reservations
+  // were learned from that history (2026-09-12) every task with a
+  // recorded peak was over any budget and ran alone. Measured, not
+  // assumed: `tests/runner.test.ts` allocates a known number of bytes
+  // and reads the peak back within a bounded factor of it.
+  // A reading at or under the parent's own mark is the parent's (see
+  // `ownRssHighWater`): the child's peak is unknown, bounded by it.
+  return usage.maxRSS > floorBytes ? { cpuMs, peakRssBytes: usage.maxRSS } : { cpuMs }
 }