@vzn/vx 0.0.645 → 0.0.648

package/src/exec/executor.ts

@@ -3,18 +3,20 @@
 // 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`. An `exec.interactive` task reaches the local one
+// Persistent tasks (`exec.persistent`) never reach an executor as tasks: a
+// worker cannot hand the submitter a listening port. A `servers` executor
+// is handed a task's persistent dependencies instead (`ExecuteRequest.servers`)
+// and starts them where it runs the task; the rest stay on `runPersistent`. An `exec.interactive` task reaches the local one
 // only: no plugin can hand it this terminal.
 //
 // 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 { SandboxConfig } from '../config.js'
 import type { CaptureConfig, RunResult } from './runner.js'
 import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
-import { UserError } from '../util/index.js'
+import { thrownMessage, UserError, type ui } from '../util/index.js'
 
 /** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
 export interface ExecuteSandbox {
@@ -34,6 +36,12 @@ export interface ExecuteSandbox {
    */
   readonly reportLinked: readonly string[]
   readonly config: ResolvedSandboxConfig
+  /**
+   * A cached task's: the project directories its key answers for, which
+   * an executor that builds the request again where it runs, on that
+   * machine's paths and platform, hands `sandboxRequestFor`.
+   */
+  readonly keyed?: readonly string[]
 }
 
 /** One declared input file, as the cache key saw it. */
@@ -77,6 +85,24 @@ export interface TaskInputs {
   readonly configDigest: string
 }
 
+/** A persistent dependency a `servers` executor starts where it runs the task, as `runPersistent` does. */
+export interface ServerSpec {
+  readonly taskId: string
+  readonly command: string
+  readonly cwd: string
+  readonly env: NodeJS.ProcessEnv
+  /** `exec.persistent.readyWhen`: ready at the first output line it matches; absent, at spawn. */
+  readonly readyWhen?: string
+  /** Bounds the readiness wait. */
+  readonly timeoutMs?: number
+  /**
+   * Its `exec.sandbox`, and the directories of the projects nested in its
+   * own (a wall its grants do not reach): it starts inside that sandbox,
+   * built where it runs, as a one-shot task's.
+   */
+  readonly sandbox?: { readonly config: SandboxConfig; readonly nested: readonly string[] }
+}
+
 export interface ExecuteRequest {
   /** `${project}#${task}` — for executors that route or log by task. */
   readonly taskId: string
@@ -90,6 +116,15 @@ export interface ExecuteRequest {
    * this machine — needs a stable address, and the key is that address.
    */
   readonly cacheKey?: string
+  /**
+   * Core saves no entry under `cacheKey` after this attempt: the run's
+   * policy writes no layer (`--no-cache`, `--cache-policy local:r`), or an
+   * upstream failed under `--continue=always`, ran unkeyed or is keyless.
+   * An executor that saves a task's result for its dependants keeps it off
+   * that key too: a distributed run's worker saved it, and the next run
+   * hit an entry the user had said not to write (2026-10-24).
+   */
+  readonly unsaved?: boolean
   /**
    * Cache READS are disabled for this run (`--force` / `--no-cache`). An
    * executor that keeps its OWN remote record of executions must not serve
@@ -104,6 +139,11 @@ export interface ExecuteRequest {
    * execution under the same key.
    */
   readonly remoteOnly?: boolean
+  /**
+   * The platform to run it on, one of the task's `exec.platforms` and the
+   * executor's `platforms`: its key includes it. Absent when the task names none.
+   */
+  readonly platform?: string
   /**
    * Whether this task's outputs must land on the submitter's disk now.
    * 'eager' (or absent) = materialise as today. 'deferred' = leave them
@@ -162,6 +202,12 @@ export interface ExecuteRequest {
    * core's local executor is ever handed such a task (placement.ts).
    */
   readonly terminal?: true
+  /**
+   * The persistent tasks it depends on, through groups, for a `servers`
+   * executor: each started where the command runs, ready before it, and
+   * shared by the tasks that run there. Absent for any other executor.
+   */
+  readonly servers?: readonly ServerSpec[]
 }
 
 export interface ExecuteResult extends RunResult {
@@ -173,16 +219,40 @@ export interface ExecuteResult extends RunResult {
    * 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.
+   * state behind. An executor may answer `deferred` to an `eager` request
+   * too, when it cannot bring them here: core saves nothing from this disk.
    */
   readonly outputs?: { kind: 'disk' } | { kind: 'deferred'; materialize: () => Promise<void> }
+  /**
+   * Tracked files the command changed where it ran, workspace-relative
+   * POSIX: an executor that runs it elsewhere says so, as this disk shows
+   * none of it. One the key read withholds the save under the key, as an
+   * input changed here does.
+   */
+  readonly changed?: readonly string[]
   /**
    * 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.
+   * its worker, onto its row and frame (`<id>@<where>`), and into the
+   * run history (v44).
    */
   readonly where?: string
+  /**
+   * The cores and memory of the machine `where` names, as it reports
+   * them: the run history keeps them, so a task that used all of one
+   * reads as wanting a bigger one (`TaskResources.saturated*`).
+   */
+  readonly machine?: {
+    readonly cores: number
+    readonly memoryBytes: number
+    /**
+     * The share of a core each runnable thread got there over the task's
+     * run (1 when a core was free). On a crowded machine the CPU a task
+     * used is its share, not its need: the run history divides by this.
+     */
+    readonly cpuShare?: number
+  }
 }
 
 /** What an executor sees when a task is PLACED — once per task, before scheduling. */
@@ -193,9 +263,10 @@ export interface TaskPlacement {
   readonly command: string
   /**
    * Must run on this machine: the task is persistent, depends (transitively)
-   * on a persistent or sandboxed task, is sandboxed itself, declares
+   * on a persistent task this executor does not carry or a sandboxed one, is sandboxed itself, declares
    * `exec.remote: false`, or folds a runtime probe into its key (this
-   * machine's `node -v`). A `remote` executor is never offered such a task.
+   * machine's `node -v`) and this executor is not `runtime`. 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. */
@@ -207,6 +278,54 @@ export interface TaskExecutor {
   readonly name: string
   /** Runs the command somewhere else. Never offered a `pinnedLocal` task. */
   readonly remote?: boolean
+  /**
+   * A `remote` executor that enforces `ExecuteRequest.sandbox` where it
+   * runs the command, as the local one does. It is offered sandboxed tasks
+   * and their dependants; the request's violations come back on the result.
+   */
+  readonly sandbox?: boolean
+  /**
+   * A `remote` executor that starts a task's persistent dependencies where
+   * it runs the task (`ExecuteRequest.servers`). It is offered the
+   * dependants of a persistent task with no `exec.sandbox` and no
+   * `exec.remote: false`; that task then runs here only for a dependant
+   * placed here (2026-10-22: nothing runs on a distributed run's
+   * orchestrator).
+   */
+  readonly servers?: boolean
+  /**
+   * A `remote` executor that answers a task's `inputs.runtime` and
+   * `workspaceRuntime` probes where it runs the task (`answerRuntime`) and
+   * fails it when one answers other than `TaskInputs` says this machine
+   * did. It is offered tasks whose key folds a probe, which otherwise run
+   * here: their key holds this machine's answer (C-2).
+   */
+  readonly runtime?: boolean
+  /**
+   * A `remote` executor that runs every task of the run, so none runs on
+   * this machine; only cache hits restore here (2026-10-24: "no
+   * task should ever run on the orchestrator"). Nothing is pinned for it:
+   * it is offered `exec.remote: false` and `exec.interactive` tasks too,
+   * and starts every server a dependant needs. A task it cannot take (a
+   * platform it does not offer, one it declines, a server requested on its
+   * own) refuses the run, and a task it gives back fails.
+   */
+  readonly exclusive?: boolean
+  /**
+   * A `remote` executor that enforces `ExecuteRequest.timeoutMs` where it
+   * runs the command, timed from its start, and reports `timedOut`. Core
+   * then arms no clock of its own: armed at the request, it counted the
+   * wait for a worker still booting and killed a 1 s task with a 3 s
+   * timeout before it began (2026-10-24). The run's stop still aborts.
+   */
+  readonly timeouts?: boolean
+  /**
+   * The platforms this executor runs tasks on (`exec.platforms`' names). It
+   * is offered a task that declares `exec.platforms` only when one of them
+   * is listed, and runs it on `ExecuteRequest.platform`; an executor that
+   * declares none is never offered such a task off this machine.
+   */
+  readonly platforms?: readonly string[]
   /**
    * 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
@@ -217,9 +336,10 @@ export interface TaskExecutor {
   /** 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).
+   * The tasks placed here that will run and have NOT finished yet — called
+   * first once the run's cache has said which placed tasks it holds (those
+   * restore, so they are left out), then again after each completion (any
+   * outcome, a failure too) and when a task it left out executes after all.
    *
    * An executor that provisions something per task — a container, an
    * allocation, a pod — otherwise has to guess. `capacity` says how much it
@@ -228,11 +348,80 @@ export interface TaskExecutor {
    * 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.
+   *
+   * `missed`: of `remaining`, those whose keys the run's up-front probe
+   * found in no store (each store asked answered for every key), or, when
+   * the remote has no batch probe, those the index keeps no hit of: they
+   * will run. The rest may still restore, or were not probed (a key an upstream's outputs can
+   * change). The same set each call, changed in place.
    */
-  demand?(remaining: ReadonlySet<string>): void
+  demand?(remaining: ReadonlySet<string>, missed: ReadonlySet<string>): void
+  /**
+   * Rows the run's footer shows for this executor, `[label, text]`, the
+   * text plain or a `ui` inline (a tone colors it): what only it knows, such as the machines it ran tasks on. Asked on every
+   * frame of the live footer and once for the final one, so it is cheap;
+   * a throw shows nothing.
+   */
+  footer?(): readonly (readonly [label: string, text: ui.Inline])[]
+  /**
+   * The machines it ran the run's tasks on (`small#1`, `local`), for the
+   * run summary telemetry sinks read; asked once at the end, only when a
+   * sink is on. A throw reports none.
+   */
+  machines?(): readonly MachineReport[]
+  /**
+   * The run's end had it placed its tasks perfectly, from the run's
+   * start: what each took, replayed on the machines it could have had, for
+   * the run summary beside the real time. Asked once at the end, only when a sink is on. A throw, or
+   * anything but a finite number, reports none.
+   */
+  idealMs?(): number | undefined
+  /**
+   * Its own Chrome-trace events for `vx run --profile` (the machines it ran
+   * tasks on, in time), asked once at the end, only when the flag is set.
+   * `ts` is in microseconds of `performance.now()`; `pid` from 1, which
+   * the run moves past its own process. A throw adds none.
+   */
+  profile?(): readonly Record<string, unknown>[]
+  /**
+   * Where a task it was handed runs (`small#2`), for the live row; asked
+   * per frame. `null` while it holds the task for a machine to begin it:
+   * the row says `waiting`, and its clock starts when a machine begins it.
+   */
+  running?(taskId: string): string | null | undefined
   execute(req: ExecuteRequest): Promise<ExecuteResult>
 }
 
+/** One machine an executor ran tasks on, as the run summary reports it. */
+export interface MachineReport {
+  /** As task rows name it (`small#1`). */
+  name: string
+  /** `online`, or `gone` for one that left before the run ended. */
+  status: string
+  cores: number
+  memoryBytes: number
+  done: number
+  failed: number
+  /** From when it joined to when it left or the run ended: warm-up not counted. */
+  onlineMs: number
+  /** Time with at least one task on it, from its send to its result. */
+  busyMs: number
+  /** Cores in use at once, at the most and on average over its time online. */
+  cpuPeak: number
+  cpuAvg: number
+  /** Bytes in use at once, at the most and on average. */
+  memoryPeakBytes: number
+  memoryAvgBytes: number
+  /** Core-time its tasks used over the core-time it had, 0 to 1. */
+  utilization: number
+  /** Cores the executor booked for the tasks it ran, on average over its time online. */
+  bookedAvg?: number
+  /** From when the executor asked for it to when it joined, for one it started. */
+  warmUpMs?: number
+  /** When it was asked for (else when it joined), from the executor's start. */
+  startMs?: number
+}
+
 /**
  * What a remote executor rejects with when it gives a task back: core runs
  * the same request on the local floor and says `reason` once (a remote that
@@ -267,6 +456,8 @@ export function assertExecuteResult(
       `executor '${executor}' returned an invalid result for ${taskId}: ${what} — a plugin bug, not a task failure`,
     )
   }
+  const shown = (v: unknown): string =>
+    typeof v === 'object' && v !== null ? 'an object' : String(v as string)
   if (typeof res !== 'object' || res === null)
     fail(`${res === null ? 'null' : typeof res} (expected an object)`)
   const r = res as Record<string, unknown>
@@ -284,6 +475,46 @@ export function assertExecuteResult(
   }
   if (!Array.isArray(r['violations']))
     fail(`violations is ${typeof r['violations']} (expected an array)`)
+  // The optional fields reach the task's row, telemetry and the run
+  // history: a `where` object lost the whole run's history to a bind error
+  // naming no executor, and a `null` violation failed the task as a TypeError.
+  for (const [i, v] of (r['violations'] as unknown[]).entries()) {
+    if (typeof v !== 'object' || v === null || typeof (v as { line?: unknown }).line !== 'string')
+      fail(`violations[${i}] is not an object with a string line`)
+  }
+  const where = r['where']
+  if (where !== undefined && (typeof where !== 'string' || where === ''))
+    fail(`where is ${where === '' ? 'empty' : typeof where} (expected a non-empty string)`)
+  for (const key of ['cpuMs', 'peakRssBytes']) {
+    const n = r[key]
+    if (n !== undefined && !(typeof n === 'number' && Number.isFinite(n) && n >= 0))
+      fail(`${key} is ${shown(n)} (expected a non-negative number)`)
+  }
+  const signal = r['signal']
+  if (
+    signal !== undefined &&
+    typeof signal !== 'string' &&
+    !(typeof signal === 'number' && Number.isInteger(signal) && signal > 0)
+  )
+    fail(`signal is ${shown(signal)} (expected a name or a signal number)`)
+  if (r['timedOut'] !== undefined && typeof r['timedOut'] !== 'boolean')
+    fail(`timedOut is ${typeof r['timedOut']} (expected a boolean)`)
+  const machine = r['machine']
+  if (machine !== undefined) {
+    if (typeof machine !== 'object' || machine === null) fail('machine is not an object')
+    const m = machine as Record<string, unknown>
+    // A worker that cannot read its memory reports 0 (vx-dte's join takes it).
+    for (const [key, least] of [
+      ['cores', 'positive'],
+      ['memoryBytes', 'non-negative'],
+      ['cpuShare', 'positive'],
+    ] as const) {
+      const n = m[key]
+      if (key === 'cpuShare' && n === undefined) continue
+      if (!(typeof n === 'number' && Number.isFinite(n) && (least === 'positive' ? n > 0 : n >= 0)))
+        fail(`machine.${key} is ${shown(n)} (expected a ${least} number)`)
+    }
+  }
   const outputs = r['outputs'] as { kind?: unknown; materialize?: unknown } | undefined
   if (outputs !== undefined) {
     if (typeof outputs !== 'object' || outputs === null) fail('outputs is not an object')
@@ -293,6 +524,12 @@ export function assertExecuteResult(
     } else if (outputs.kind !== 'disk')
       fail(`outputs.kind is ${String(outputs.kind)} (expected disk or deferred)`)
   }
+  const changed = r['changed']
+  if (
+    changed !== undefined &&
+    (!Array.isArray(changed) || changed.some((f) => typeof f !== 'string'))
+  )
+    fail('changed is not an array of paths')
 }
 
 /**
@@ -307,13 +544,18 @@ export function selectExecutor(
   executors: readonly TaskExecutor[],
   task: TaskPlacement,
   label: (executor: TaskExecutor) => string = (e) => `executor '${e.name}'`,
+  /** `task.pinnedLocal` as `executor` sees it: one that enforces the sandbox or carries servers lifts some pins. */
+  pinnedFor: (executor: TaskExecutor) => boolean = () => task.pinnedLocal,
 ): TaskExecutor {
   for (const executor of executors) {
-    if (task.pinnedLocal && executor.remote === true) continue
+    const pinned = pinnedFor(executor)
+    if (pinned && executor.remote === true) continue
     if (executor.accepts === undefined) return executor
     let taken: unknown
     try {
-      taken = executor.accepts(task)
+      taken = executor.accepts(
+        pinned === task.pinnedLocal ? task : { ...task, pinnedLocal: pinned },
+      )
       // An `async accepts` answers a Promise: truthy, so the executor took
       // every task, and a rejection went unheard (the shape of H-16's admit).
       if (taken instanceof Promise) {
@@ -321,7 +563,7 @@ export function selectExecutor(
         throw new Error('returned a Promise; accepts is synchronous')
       }
     } catch (err) {
-      const m = err instanceof Error ? err.message : String(err)
+      const m = thrownMessage(err)
       throw new UserError(`${label(executor)} failed in accepts for ${task.taskId}: ${m}`)
     }
     if (taken) return executor
@@ -330,3 +572,8 @@ export function selectExecutor(
     `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.`,
   )
 }
+
+/** This machine as `exec.platforms` names it: `os-arch` as Bun reports them, `linux-x64`. */
+export function hostPlatform(): string {
+  return `${process.platform}-${process.arch}`
+}

package/src/exec/index.ts

@@ -9,7 +9,9 @@ export {
   VX_RUN_WORKSPACE_ENV,
 } from './env.js'
 export {
+  lineEnds,
   runCommand,
+  restoreTerminalModes,
   runPersistent,
   PersistentReadyError,
   withForwardArgs,
@@ -19,6 +21,7 @@ export {
   type CaptureConfig,
   execWord,
   maskCaptured,
+  isDroppedOutputChunk,
   BoundedCapture,
   type CapturedChunk,
 } from './runner.js'
@@ -48,17 +51,20 @@ export {
 } from './sandbox-paths.js'
 export { bindableWrites, punchWalls } from './sandbox-binds.js'
 export { isLocalExecutor, localExecutor } from './local-executor.js'
-export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'
-export { sampleTrees } from './proc-sample.js'
+export { holdGroups, killTree, pauseTree, untilGroupsGone } from './kill-tree.js'
+export { sampleTrees, type TreeUsage } from './proc-sample.js'
 export {
   assertExecuteResult,
   executorFallback,
+  hostPlatform,
   isExecutorFallback,
   selectExecutor,
   type ExecuteRequest,
   type ExecuteResult,
   type ExecuteSandbox,
   type InputFile,
+  type MachineReport,
+  type ServerSpec,
   type TaskExecutor,
   type TaskInputs,
   type TaskPlacement,

package/src/exec/kill-tree.ts

@@ -328,6 +328,21 @@ export function killTree(child: Child, signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL')
   }
 }
 
+/**
+ * Stop or continue `child`'s group with vx (Ctrl-Z, `fg`). Straight to
+ * the group, never down a sandbox's channel: its watcher passes one
+ * signal and is gone. Under a Linux sandbox that stops bwrap, and the
+ * command inside blocks once its output pipe fills.
+ */
+export function pauseTree(child: Child, signal: 'SIGSTOP' | 'SIGCONT'): void {
+  if (!(child.pid > 0) || goneGroups.has(child)) return
+  try {
+    process.kill(-child.pid, signal)
+  } catch {
+    // The group is gone, or not ours: nothing of it to stop.
+  }
+}
+
 /**
  * How often a group whose leader has exited is asked again whether any
  * member is left. Only a group that outlived its leader is polled.

package/src/exec/local-executor.ts

@@ -2,7 +2,7 @@
 // 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
+// (2026-09-05). An executor plugin places work ELSEWHERE; its
 // absence is "here".
 import { runCommand, signalExitCode, stopSignal } from './runner.js'
 import { runSandboxed } from './sandbox-runtime.js'

package/src/exec/proc-sample.ts

@@ -8,7 +8,7 @@
 // counted; nor is the CPU of a descendant that already exited.
 
 import { readdir, readFile } from 'node:fs/promises'
-import { procfsIsOwn } from '../util/index.js'
+import { helperEnv, procfsIsOwn } from '../util/index.js'
 
 export interface TreeUsage {
   /** CPU time of the live tree, user + system, in ms. */
@@ -19,7 +19,10 @@ export interface TreeUsage {
 
 interface Proc {
   ppid: number
+  /** Its own CPU and, on Linux, what its reaped children used (`cutime`, `cstime`). */
   cpuMs: number
+  /** The executable's name; Linux only. */
+  comm?: string
   /** Resident KiB when the table carries it; Linux reads it per tree member. */
   rssKiB?: number
 }
@@ -32,7 +35,11 @@ interface Proc {
 const TICK_MS = 10
 
 /** Each root's tree usage; a root no longer alive has no entry. */
-export async function sampleTrees(roots: readonly number[]): Promise<Map<number, TreeUsage>> {
+export async function sampleTrees(
+  roots: readonly number[],
+  /** Members not counted (their children still are): the sandbox's own tracer. */
+  skip?: ReadonlySet<string>,
+): Promise<Map<number, TreeUsage>> {
   const out = new Map<number, TreeUsage>()
   if (roots.length === 0) return out
   const table = process.platform === 'linux' ? await linuxTable() : await psTable()
@@ -49,7 +56,8 @@ export async function sampleTrees(roots: readonly number[]): Promise<Map<number,
     const stack = [root]
     while (stack.length > 0) {
       const pid = stack.pop()!
-      tree.push(pid)
+      const comm = table.get(pid)!.comm
+      if (skip === undefined || comm === undefined || !skip.has(comm)) tree.push(pid)
       for (const c of children.get(pid) ?? []) stack.push(c)
     }
     let cpuMs = 0
@@ -86,12 +94,16 @@ async function linuxTable(): Promise<Map<number, Proc> | undefined> {
       }
       // `<pid> (<comm>) <state> <ppid> …` — comm may hold spaces and parens,
       // so the fields start after the LAST ')': state is [0], ppid [1],
-      // utime [11], stime [12].
-      const f = stat.slice(stat.lastIndexOf(')') + 2).split(' ')
+      // utime [11], stime [12], cutime [13], cstime [14]. The reaped
+      // children's share keeps a tree's sum from dropping when a member
+      // exits: what a task's short-lived processes used stays counted.
+      const close = stat.lastIndexOf(')')
+      const f = stat.slice(close + 2).split(' ')
       if (f[0] === 'Z' || f[0] === 'X') return
       table.set(Number(entry), {
         ppid: Number(f[1]),
-        cpuMs: (Number(f[11]) + Number(f[12])) * TICK_MS,
+        cpuMs: (Number(f[11]) + Number(f[12]) + Number(f[13]) + Number(f[14])) * TICK_MS,
+        comm: stat.slice(stat.indexOf('(') + 1, close),
       })
     }),
   )
@@ -113,7 +125,9 @@ async function linuxRssKiB(pid: number): Promise<number> {
 async function psTable(): Promise<Map<number, Proc> | undefined> {
   let text: string
   try {
+    // It runs beside the tasks, readable by them (`ps eww`): PATH alone.
     const ps = Bun.spawn(['ps', '-A', '-o', 'pid=,ppid=,rss=,time='], {
+      env: helperEnv(),
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'ignore',
@@ -153,3 +167,53 @@ export function psTimeMs(s: string): number | undefined {
   for (const n of parts) seconds = seconds * 60 + n
   return Math.round((days * 86_400 + seconds) * 1000)
 }
+
+/** How often a watched tree is looked at; one timer serves every tree. */
+const WATCH_EVERY_MS = 250
+
+const watched = new Map<number, TreeUsage & { looks: number }>()
+let watchTimer: ReturnType<typeof setInterval> | undefined
+let looking = false
+const SKIP = new Set(['strace'])
+
+async function look(): Promise<void> {
+  if (looking) return
+  looking = true
+  try {
+    const usage = await sampleTrees([...watched.keys()], SKIP)
+    for (const [pid, u] of usage) {
+      const w = watched.get(pid)
+      if (w === undefined) continue
+      w.cpuMs = Math.max(w.cpuMs, u.cpuMs)
+      w.rssBytes = Math.max(w.rssBytes, u.rssBytes)
+      w.looks++
+    }
+  } catch {
+    // A failed look is a missing point.
+  } finally {
+    looking = false
+  }
+}
+
+/**
+ * Watch a running tree until `stop`, which answers the most CPU and the
+ * peak resident memory any look saw; none when no look landed (a task
+ * shorter than one interval). The sandbox's answer on Linux, where the
+ * wait never sees what bwrap's pid namespace used.
+ */
+export function watchTree(pid: number): { stop(): TreeUsage | undefined } {
+  const w = { cpuMs: 0, rssBytes: 0, looks: 0 }
+  watched.set(pid, w)
+  watchTimer ??= setInterval(() => void look(), WATCH_EVERY_MS)
+  watchTimer.unref?.()
+  return {
+    stop() {
+      if (watched.get(pid) === w) watched.delete(pid)
+      if (watched.size === 0 && watchTimer !== undefined) {
+        clearInterval(watchTimer)
+        watchTimer = undefined
+      }
+      return w.looks === 0 ? undefined : { cpuMs: w.cpuMs, rssBytes: w.rssBytes }
+    },
+  }
+}