@vzn/vx 0.0.16 → 0.0.18

package/src/config.ts

@@ -19,18 +19,12 @@ export interface WorkspaceConfig {
    * `vx run`. See `docs/design/extension-protocol-2026-06.md` §5.
    */
   plugins?: readonly Plugin[]
-  /**
-   * Opt in to history-aware predictive scheduling. When `true` and
-   * `cache.db` has prior runs, the scheduler picks the next ready
-   * task by expected remaining critical-path duration (HistoryTable
-   * p50) instead of the static reverse-deps count.
-   */
-  predictive?: boolean
 }
 
 /**
- * Structural plugin shape — any subset of the run-level capabilities
- * (`backend`/`cache`/`telemetry`/`eventSink`) plus optional
+ * Structural plugin shape — any subset of the pipeline stages
+ * (`config`/`project`/`graph`/`key`/`schedule`), run-level capabilities
+ * (`cache`/`executor`/`telemetry`) and CLI `commands`, plus optional
  * `setup`/`teardown`. The fully-typed `VxPlugin` lives in
  * `src/orchestrator/plugin.ts` and is what users import; this is a
  * re-declaration with opaque function types so `config.ts` stays a leaf
@@ -39,10 +33,15 @@ export interface WorkspaceConfig {
  */
 export interface Plugin {
   readonly name: string
-  backend?(ctx: unknown): unknown
+  config?(workspace: unknown, ctx: unknown): unknown
+  project?(config: unknown, ctx: unknown): unknown
+  graph?(nodes: unknown, ctx: unknown): unknown
+  key?(task: unknown, ctx: unknown): unknown
+  schedule?(nodes: unknown, ctx: unknown): unknown
+  readonly commands?: Readonly<Record<string, unknown>>
   cache?(ctx: unknown): unknown
+  executor?(ctx: unknown): unknown
   telemetry?(ctx: unknown): unknown
-  eventSink?(ctx: unknown): unknown
   setup?(ctx: unknown): void | Promise<void>
   teardown?(): void | Promise<void>
 }
@@ -57,7 +56,13 @@ export interface TaskConfig {
    * Optional one-line description of what this task does. Surfaced in
    * the interactive task picker and the `--dry` text view so users
    * can grep for what each task does without opening every config.
-   * Pure metadata — no effect on caching, scheduling, or execution.
+   *
+   * No effect on scheduling or execution. It DOES participate in the
+   * cache key, because the key hashes the whole resolved task config
+   * (`docs/caching.md`, step 5) — deliberate: editing a description
+   * isn't a correctness change, but a one-off re-run costs little and
+   * carving exceptions out of the resolved object is what invites
+   * stale hits.
    */
   description?: string
   /**
@@ -211,6 +216,20 @@ export interface SandboxNetworkConfig {
 export interface ExecConfig {
   /** Shell command to run, from the project's directory. */
   command: string
+  /**
+   * `false` pins the task to this machine: it is never offered to a remote
+   * executor (it talks to a local daemon, the network, Docker, …). Default
+   * `true`. Tasks that are persistent, or depend on one, are pinned
+   * regardless — a worker cannot reach a port on the submitter.
+   *
+   * `'only'` is the inverse pin: the task exists to produce a REMOTE input
+   * tree (the canonical case is `pnpm install` feeding remote workers) and is
+   * a NO-OP on this machine — never executed locally, its declared outputs
+   * never cleaned or restored on this disk. With no remote executor declared
+   * the task succeeds without running and dependents use whatever ambient
+   * state the machine has, exactly as they did before the field existed.
+   */
+  remote?: boolean | 'only'
   /** Environment exposed to the child process. */
   env?: ExecEnv
   /**
@@ -271,19 +290,17 @@ export interface ExecConfig {
  * rejects unknown keys.
  */
 export interface ResourcesConfig {
+  /** CPU cores; fractional is allowed (`0.5`). */
+  cpus?: number
+  /** Megabytes. `memory: 4096` is four gigabytes. */
+  memory?: number
   /**
-   * CPU units (fractional ok, e.g. `0.5`), or a `"<n>%"` string of the
-   * CPU budget (the run's `concurrency`). `cpus: "50%"` on a budget of 8
-   * reserves 4 units.
-   */
-  cpus?: number | string
-  /**
-   * Bytes, a size string (`"2GB"`, `"512MB"` — K/M/G/T, powers of 1024),
-   * or a `"<n>%"` string of the memory budget (`os.totalmem()` unless
-   * overridden with `--memory` — pass `--memory` in cgroup-limited
-   * containers, where `os.totalmem()` reports the HOST's RAM).
+   * The container image this task needs, MATCHED against what a worker
+   * advertises — never a provisioning instruction, since a distributed
+   * executor's workers belong to whoever runs the fleet. Ignored by
+   * executors that do not run containers.
    */
-  memory?: number | string
+  image?: string
 }
 
 export interface PersistentConfig {

package/src/exec/env.ts

@@ -8,7 +8,13 @@ import path from 'node:path'
 //   3. define: explicit name=value pairs from the task config.
 //   4. binPaths prepended to PATH (after all the above resolve PATH).
 
-const ESSENTIAL_ENV: readonly string[] = [
+/**
+ * Exported so the schema doc's enumeration of it can be PINNED against the
+ * real list: a hand-copied allowlist is how the two drift, and a reader
+ * asking "what does my build script actually see?" is asking a
+ * security-shaped question that a stale list answers wrongly.
+ */
+export const ESSENTIAL_ENV: readonly string[] = [
   'PATH',
   'HOME',
   'SHELL',

package/src/exec/executor.ts

@@ -0,0 +1,239 @@
+// 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 ships
+// no executor of its own: `@vzn/vx/plugins/local-executor` is the
+// in-process spawn, declared in vx.workspace.ts like any other. 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[]
+  readonly config: ResolvedSandboxConfig
+  /**
+   * True when an EMPTY violation store on a CLEAN exit will be read as
+   * PROOF (`--verify=inputs` treats zero violations as `proven-complete`).
+   * On macOS the store is fed asynchronously from the unified log, so the
+   * runtime must pay the bounded settle window even for a 0-exit — a leaky
+   * task that swallows its own read error exits 0, and without the wait a
+   * merely-late violation record turns into a false pass of the verify.
+   */
+  readonly settleOnCleanExit: boolean
+}
+
+/** 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 (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
+  /**
+   * `exec.resources` VERBATIM — CPU cores, megabytes, and the image a
+   * worker must be running for this task to be routed to it. All three are
+   * requirements MATCHED against what an executor has, never instructions
+   * to build a machine: a distributed executor's workers belong to whoever
+   * runs the fleet.
+   *
+   * Placement is where this belongs: `exec.resources` is stripped from the
+   * cache key precisely because it decides WHERE a task fits, never what
+   * it produces.
+   */
+  readonly resources?: Readonly<{ cpus?: number; memory?: number; image?: string }>
+}
+
+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(', ')}). Declare localExecutorPlugin() after the executor that declined to run such tasks locally.`,
+  )
+}

package/src/exec/index.ts

@@ -2,12 +2,30 @@
 // 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 {
+  runCommand,
+  runPersistent,
+  shellQuote,
+  signalExitCode,
+  type CaptureConfig,
+} from './runner.js'
 export {
   initSandbox,
   probeSandbox,
   resetSandbox,
   resolveSandboxConfig,
   runSandboxed,
+  type DeniedCall,
+  type ResolvedSandboxConfig,
   type SandboxViolation,
 } from './sandbox-runtime.js'
+export {
+  selectExecutor,
+  type ExecuteRequest,
+  type ExecuteResult,
+  type ExecuteSandbox,
+  type InputFile,
+  type TaskExecutor,
+  type TaskInputs,
+  type TaskPlacement,
+} from './executor.js'

package/src/exec/runner.ts

@@ -25,6 +25,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 +48,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
@@ -144,19 +160,79 @@ export function signalExitCode(signal: string): number {
  * on its own. A no-op (never fires, nothing to clear) when `timeoutMs`
  * is undefined.
  */
+/**
+ * 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
+
 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
+  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'), 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 +243,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 +275,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 +295,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 +328,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 +343,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)
+          }
         }
       }
     }
@@ -340,8 +421,6 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   return {
     child,
     ready,
-    bufferedStdout: () => bufferedStdout,
-    bufferedStderr: () => bufferedStderr,
     readyMs: () => (readyAt ?? Date.now()) - start,
   }
 }
@@ -376,15 +455,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)
@@ -401,12 +484,16 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
 
 /**
  * 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 +517,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 {