@vzn/vx 0.0.644 → 0.0.646

package/src/orchestrator/run.ts

@@ -24,7 +24,7 @@ import {
 } from '../exec/index.js'
 import { DeferredOutputs } from './deferred-outputs.js'
 import { resolveDownloadModes } from './download-policy.js'
-import type { TaskExecutor } from '../exec/index.js'
+import type { MachineReport, TaskExecutor } from '../exec/index.js'
 import {
   deadServerBehind,
   declaredTask,
@@ -51,6 +51,7 @@ import {
   detectColors,
   type ColorSupport,
   SecretBroker,
+  type ui,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
@@ -114,6 +115,7 @@ import {
   type ShortCircuit,
 } from './local-shortcircuit.js'
 import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
+import { askRemote, serversToHold } from './held-servers.js'
 
 import { writeRunFailures } from './run-failures.js'
 import { assembleRunRecords, recordLateRemoteErrors } from './run-records.js'
@@ -136,6 +138,7 @@ import {
 } from '../history/index.js'
 import type { RunOptions, RunSummary } from './options.js'
 import { withRunSettings } from './run-settings.js'
+import { cacheFacts, taskArtifacts } from './task-artifacts.js'
 import { resolveSetting } from '../settings.js'
 
 // Per run, never shared: a `vx watch` process runs many, and a shared map
@@ -145,6 +148,7 @@ const emptyShortCircuit = (): ShortCircuit => ({
   restoreTier: new Set(),
   uncachedKeys: new Map(),
   groupKeys: new Map(),
+  remoteAsk: new Map(),
 })
 
 /**
@@ -547,6 +551,8 @@ async function runOnBus(
       cacheDir: prepared.cacheDir,
       warn: warnOf(log),
       concurrency,
+      artifacts: taskArtifacts(prepared.cache, prepared.workspaceRoot),
+      cacheFacts: () => cacheFacts(prepared.remotes, prepared.cacheRefs),
     }),
   )
   // Placement: decided ONCE per task, before scheduling, so the scheduler
@@ -744,10 +750,19 @@ async function runOnBus(
       n.config.exec?.persistent !== undefined ||
       n.config.cache === undefined ||
       !(policy.localRead || policy.remoteRead)
+    // Only what runs here arms this machine's sandbox: a `sandbox` executor
+    // enforces it where it runs the task, so a distributed run's
+    // orchestrator needs none (owner, 2026-10-22).
     const sandboxed =
       sandboxArmer === null
         ? []
-        : [...nodes.values()].filter((n) => n.config.exec?.sandbox !== undefined)
+        : [...nodes.values()].filter(
+            (n) =>
+              n.config.exec?.sandbox !== undefined &&
+              (n.config.exec.persistent === undefined
+                ? localPlaced.has(n.id)
+                : !placements.carried.has(n.id)),
+          )
     let prewarming: Promise<void> | undefined
     const prewarm = (): void => {
       prewarming ??= sandboxArmer?.arm().catch(() => {})
@@ -800,7 +815,16 @@ async function runOnBus(
 
     // Run context for the footer. The top-of-run header is gone — the
     // banner now lives in the summary, where the eye lands at the end.
+    const footers = executors.filter((e) => e.footer !== undefined)
+    const placers = executors.filter((e) => e.running !== undefined)
     const runContext = {
+      ...(footers.length > 0 ? { executorRows: () => footers.flatMap(executorFooter) } : {}),
+      ...(placers.length > 0
+        ? {
+            whereRunning: (id: string) =>
+              placers.map((e) => executorWhere(e, id)).find((w) => w !== undefined),
+          }
+        : {}),
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
@@ -810,11 +834,14 @@ async function runOnBus(
         localWrite: policy.localWrite,
         remote: remoteCacheEnabled && (policy.remoteRead || policy.remoteWrite),
         traffic: prepared.localCache.traffic,
+        downloads: prepared.localCache.downloads,
+        uploads: prepared.localCache.uploads,
         notDownloaded: () => deferredOutputs.pending().length,
       },
       concurrency,
       workspaceProjectCount,
-      runId: undefined as string | undefined,
+      // Live too: a long run is read while it runs (M, 2026-10-21).
+      runId,
     }
 
     // Asked only when a plugin declares `output`: a plain run pays nothing.
@@ -900,10 +927,19 @@ async function runOnBus(
       shouldShortCircuit(nodes, policy) && (remote || cache === prepared.localCache)
         ? prepared.localCache.holdsNothing()
         : false
+    // Behind a remote, a server's dependants need their keys up front even
+    // on an empty store: the remote may hold them all, and then the server
+    // never starts (`held-servers.ts`).
+    const askForServers =
+      remote &&
+      policy.remoteRead &&
+      [...nodes.values()].some(
+        (n) => n.config.exec?.persistent !== undefined && !n.requested && n.surfaced !== true,
+      )
     // A remote may still hold what an empty local store does not: the
     // prefetch asks it, and no confirmed miss warms the sandbox early.
-    if (coldLocal && !remote) prewarm()
-    else if (!coldLocal && shouldShortCircuit(nodes, policy)) {
+    if (coldLocal && !remote && sandboxed.length > 0) prewarm()
+    else if ((!coldLocal || askForServers) && shouldShortCircuit(nodes, policy)) {
       shortCircuit = await step('vx:keys', () =>
         startLocalShortCircuit({
           nodes,
@@ -1156,6 +1192,16 @@ async function runOnBus(
       // runs ahead of their deps as low-priority worker-slot backfill.
       // Empty when the short-circuit didn't fire → byte-identical.
       restoreTier: shortCircuit.restoreTier,
+      ...(askForServers
+        ? {
+            heldServers: askRemote(
+              serversToHold(nodes, shortCircuit.restoreTier, shortCircuit.remoteAsk),
+              nodes,
+              shortCircuit,
+              cache,
+            ),
+          }
+        : {}),
     })
     stop.graphDone()
     reprioritize = undefined
@@ -1295,9 +1341,15 @@ async function runOnBus(
         recordHistory(() => cache.recordRunBundle(records))
         recordFailures(list)
       })
+    } else if (stop.stoppedBy !== undefined) {
+      // Stopped: not a run `vx last` lists (item 854), but what finished is
+      // measured, or the next run knows none of it (M, 2026-10-21).
+      const ended = list.filter((o) => o.status !== 'aborted' && o.status !== 'skipped')
+      stepSync('vx:history', () =>
+        recordHistory(() => prepared.localCache.recordRuns(recordsOf(ended, false).runs)),
+      )
     }
     mark('record history')
-    runContext.runId = runId
     // Drain any still-in-flight background prefetches before closing the
     // cache handle — a prefetch ingesting into a closed SQLite DB would
     // throw. Tasks that resolved as local hits never awaited their
@@ -1343,6 +1395,7 @@ async function runOnBus(
         abortedCount: list.filter((o) => o.status === 'aborted' && !isGroupTask(o.node)).length,
         stages: stageTimes(),
         uploads: prepared.localCache.uploads,
+        machines: executors.flatMap(executorMachines),
       })
       telemetry.emitSummary(summary)
       const sinks = telemetry
@@ -1814,3 +1867,39 @@ function canonical(dir: string): string {
     return path.resolve(dir)
   }
 }
+
+/** An executor's footer rows; a plugin's throw or bad shape shows none. */
+function executorFooter(e: TaskExecutor): (readonly [string, ui.Inline])[] {
+  try {
+    const rows = e.footer?.()
+    if (!Array.isArray(rows)) return []
+    return rows.filter(
+      (r): r is readonly [string, ui.Inline] =>
+        Array.isArray(r) &&
+        typeof r[0] === 'string' &&
+        (typeof r[1] === 'string' || (typeof r[1] === 'object' && r[1] !== null)),
+    )
+  } catch {
+    return []
+  }
+}
+
+function executorMachines(e: TaskExecutor): readonly MachineReport[] {
+  try {
+    const m = e.machines?.()
+    return Array.isArray(m) ? m : []
+  } catch {
+    return []
+  }
+}
+
+/** Where `e` says a task runs, or `null` while it waits; a throw or anything else says nothing. */
+function executorWhere(e: TaskExecutor, id: string): string | null | undefined {
+  try {
+    const w = e.running?.(id)
+    if (w === null) return null
+    return typeof w === 'string' && w !== '' ? w : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/orchestrator/sandbox-request.ts

@@ -45,6 +45,11 @@ export interface SandboxArmer {
   readonly armed: boolean
 }
 
+/** What the run's sandbox union reads of a task: a `TaskNode`, or an agent's order. */
+export interface SandboxedNode {
+  readonly config: { readonly exec?: { readonly sandbox?: ExecConfig['sandbox'] } }
+}
+
 /**
  * What SRT's run-wide `initialize()` is armed with, folded from every
  * sandboxed task in the graph — or `null` when the run has none.
@@ -71,7 +76,7 @@ export interface SandboxRunUnion {
   weakerNested: boolean
 }
 
-export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | null {
+export function sandboxRunUnion(nodes: Iterable<SandboxedNode>): SandboxRunUnion | null {
   const sandboxed = [...nodes].filter((n) => n.config.exec?.sandbox !== undefined)
   if (sandboxed.length === 0) return null
   const weakerNested = sandboxed.every((n) => n.config.exec?.sandbox?.weakerWhenNested === true)
@@ -119,7 +124,7 @@ export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | nu
  * port list (its bridge is a unix socket the task's side creates), lifts
  * it for the run. macOS keeps per-task precision through vx's own rules.
  */
-export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
+export function prepareSandbox(nodes: Iterable<SandboxedNode>): SandboxArmer | null {
   const union = sandboxRunUnion(nodes)
   if (union === null) return null
   const { domains, deniedDomains, unixSockets, gitConfig, weakerNested } = union
@@ -180,7 +185,7 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
  * with no `cache`, which has no key to be stale.
  */
 export async function sandboxRequestFor(
-  node: TaskNode,
+  node: Pick<TaskNode, 'projectDir'>,
   sandbox: NonNullable<ExecConfig['sandbox']>,
   workspaceRoot: string,
   keyed: ReadonlySet<string> | undefined,
@@ -285,6 +290,7 @@ export async function sandboxRequestFor(
     // withholding exists to stop, not the wall.
     reportLinked: links.withheld.map((w) => w.dir),
     config,
+    ...(keyed === undefined ? {} : { keyed: [...keyed] }),
   }
   return { sandbox: request, placeholders, withheld: links.withheld }
 }

package/src/orchestrator/task-artifacts.ts

@@ -0,0 +1,142 @@
+// Task entries by key for an executor that runs a task on another machine
+// (`ExecutorContext.artifacts`, `CommandContext.artifacts`): the machine
+// that ran it saves its outputs and output under the key the order named,
+// and the one that needs them restores them, through the workspace's own
+// cache (design packages/vx/docs/design/dte-2026-10.md, "Files").
+
+import {
+  type CacheLayer,
+  type ResolvedRemote,
+  resolveOutputTree,
+  resolveWorkspaceOutputs,
+} from '../cache/index.js'
+import { secretMask } from '../util/index.js'
+import { decodeOutputLog, encodeOutputLog } from './output-log.js'
+
+/** The task a `TaskArtifacts` call names: where its outputs are and what ran. */
+export interface ArtifactTask {
+  /** `project#task`. */
+  readonly id: string
+  /** Absolute. */
+  readonly projectDir: string
+  readonly command: string
+  /** Its `cache.outputs`: project-relative `files`, root-relative `workspaceFiles`. */
+  readonly outputs: {
+    readonly files: readonly string[]
+    readonly workspaceFiles: readonly string[]
+  }
+  /** The projects inside `projectDir` (absolute), whose files are not its outputs. */
+  readonly nestedProjectDirs?: readonly string[]
+}
+
+/** What a task's run left besides its files: its output, and its time and usage. */
+export interface ArtifactRun {
+  readonly stdout: string
+  readonly stderr: string
+  readonly durationMs: number
+  readonly cpuMs?: number
+  readonly peakRssBytes?: number
+  /** Its environment: a secret value in it is masked out of the stored output. */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+export interface TaskArtifacts {
+  /**
+   * Keeps the files `task`'s outputs match, and its output, as entry
+   * `key`: here, and on each remote the workspace writes. Resolves once
+   * every upload has settled; a remote that fails degrades as a run's
+   * upload does.
+   */
+  save(key: string, task: ArtifactTask, run: ArtifactRun): Promise<void>
+  /**
+   * Lays entry `key`'s files into the workspace, from the local store or
+   * else the first remote holding it, and resolves its output; null when
+   * none holds it. A key restored here and then saved is not uploaded
+   * again.
+   */
+  restore(key: string, task: ArtifactTask): Promise<{ stdout: string; stderr: string } | null>
+}
+
+export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArtifacts {
+  return {
+    async save(key, task, run) {
+      const [tree, wsFiles] = await Promise.all([
+        resolveOutputTree({
+          projectDir: task.projectDir,
+          outputs: task.outputs.files,
+          nestedProjectDirs: [...(task.nestedProjectDirs ?? [])],
+        }),
+        resolveWorkspaceOutputs({ workspaceRoot, outputs: task.outputs.workspaceFiles }),
+      ])
+      const mask = secretMask([process.env, run.env ?? {}])
+      const log = encodeOutputLog([
+        { text: run.stdout, err: false },
+        { text: run.stderr, err: true },
+      ])
+      await cache.save({
+        hash: key,
+        projectDir: task.projectDir,
+        outputFiles: tree.files,
+        ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
+        workspaceRoot,
+        ...(wsFiles.length > 0 ? { workspaceOutputFiles: wsFiles } : {}),
+        entry: {
+          taskId: task.id,
+          command: mask?.mask(task.command) ?? task.command,
+          durationMs: run.durationMs,
+          stdout: mask?.mask(log) ?? log,
+          ...(run.cpuMs !== undefined ? { cpuMs: run.cpuMs } : {}),
+          ...(run.peakRssBytes !== undefined ? { peakRssBytes: run.peakRssBytes } : {}),
+        },
+      })
+      await cache.drainUploads?.()
+    },
+
+    async restore(key, task) {
+      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      if (entry === null) return null
+      await cache.restoreOutputs(key, task.projectDir, workspaceRoot, task.outputs)
+      let stdout = ''
+      let stderr = ''
+      for (const c of decodeOutputLog(entry.stdout)) {
+        if (c.err) stderr += c.text
+        else stdout += c.text
+      }
+      return { stdout, stderr }
+    },
+  }
+}
+
+/**
+ * What a run's cache is read under, for a machine that runs its tasks
+ * (`ExecutorContext.cacheFacts`, `CommandContext.artifactsFor`): the
+ * refs the run worked out, so that machine reads as the run would, and
+ * the access each remote lent, by plugin.
+ */
+export interface CacheFacts {
+  /** `CacheContext.refs`. */
+  readonly refs: readonly string[]
+  /** Plugin name → the token its remote's `lend` gave. */
+  readonly lent: Readonly<Record<string, string>>
+  /** Epoch ms: the first lent token's end, before which to ask again. */
+  readonly expiresAt?: number
+}
+
+/** The run's `CacheFacts`: each readable remote's `lend`, asked now; one that throws lends nothing. */
+export async function cacheFacts(
+  remotes: readonly ResolvedRemote[],
+  refs: readonly string[],
+): Promise<CacheFacts> {
+  const lent: Record<string, string> = {}
+  let expiresAt: number | undefined
+  await Promise.all(
+    remotes.map(async (r) => {
+      if (r.plugin === undefined || r.remote.lend === undefined || !r.read) return
+      const got = await r.remote.lend().catch(() => undefined)
+      if (got === undefined) return
+      lent[r.plugin] = got.token
+      if (got.expiresAt !== undefined) expiresAt = Math.min(expiresAt ?? Infinity, got.expiresAt)
+    }),
+  )
+  return { refs, lent, ...(expiresAt === undefined ? {} : { expiresAt }) }
+}

package/src/orchestrator/task-hash.ts

@@ -97,9 +97,7 @@ export interface ComputeHashArgs {
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   if (isKeyless(args.node.config)) return keylessHash(args.node.id)
-  const key = await taskHash(args)
-  args.cache.noteKey?.(args.node.id, key)
-  return key
+  return taskHash(args)
 }
 
 async function taskHash(args: ComputeHashArgs): Promise<string> {
@@ -299,6 +297,16 @@ export async function movedInput(
   return undefined
 }
 
+/** A task's `filesToken`, as its key's fold memo probe takes it. */
+export function taskFilesToken(
+  args: Pick<
+    ComputeHashArgs,
+    'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'gitFilesCache' | 'hashCache'
+  >,
+): string | undefined {
+  return filesToken(inputsArgs({ ...args, upstream: [], cache: undefined as never }))
+}
+
 /** What `resolveInputs` is asked for a task's key. */
 function inputsArgs(args: ComputeHashArgs): ResolveInputsArgs {
   const cfg = args.node.config
@@ -413,7 +421,7 @@ async function resolveKeyInput(
  * each task's config object is created once per run, so a hit there
  * skips the JSON.stringify + xxh3 entirely.
  */
-function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
+export function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
   if (hashCache) {
     const cached = hashCache.taskConfig.get(cfg)
     if (cached !== undefined) return cached

package/src/orchestrator/task-process.ts

@@ -11,6 +11,7 @@ import {
   PM_EXEC_ENV,
   VX_RUN_TASK_ENV,
   VX_RUN_WORKSPACE_ENV,
+  type ServerSpec,
 } from '../exec/index.js'
 import type { TaskNode } from '../graph/index.js'
 import { parseDuration } from '../util/index.js'
@@ -89,6 +90,21 @@ export function taskTimeoutMs(step: ExecConfig): number | undefined {
   return step.timeout === undefined ? undefined : parseDuration(step.timeout)!
 }
 
+/** Persistent task `node` as a `servers` executor starts it: no forwarded args, which a dependency never gets. */
+export function serverSpec(node: TaskNode, workspaceRoot: string): ServerSpec {
+  const step = node.config.exec!
+  const timeoutMs = taskTimeoutMs(step)
+  const readyWhen = step.persistent?.readyWhen
+  return {
+    taskId: node.id,
+    command: step.command,
+    cwd: node.projectDir,
+    env: taskEnv(node, step, workspaceRoot),
+    ...(readyWhen === undefined ? {} : { readyWhen }),
+    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+  }
+}
+
 export function isAborted(signal: AbortSignal | undefined): boolean {
   return signal?.aborted === true
 }

package/src/orchestrator/telemetry-host.ts

@@ -18,6 +18,7 @@ import type {
   RunSummaryRecord,
   TelemetryContext,
   TelemetrySink,
+  TreeLoad,
 } from './telemetry.js'
 import { settleWithin, teardownTimeoutMs } from '../util/index.js'
 import { createTelemetrySource } from './telemetry.js'
@@ -32,7 +33,7 @@ export interface TelemetryHandle {
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
-  readonly track?: (taskId: string, pid: number) => () => void
+  readonly track?: (taskId: string, pid: number) => () => TreeLoad | undefined
 }
 
 /** Reject anything that is not sink-shaped, naming what arrived. */

package/src/orchestrator/telemetry.ts

@@ -16,7 +16,7 @@
 // what or how tasks run. Contrast `cache`/`executor`, which return objects
 // core calls INTO; those are the behavior capabilities, kept separate.
 
-import { sampleTrees } from '../exec/index.js'
+import { sampleTrees, type MachineReport } from '../exec/index.js'
 import {
   type CacheSource,
   deriveCacheSource,
@@ -274,6 +274,12 @@ export interface RunSummaryRecord {
    * Absent when nothing was uploaded or tried. Additive.
    */
   uploads?: { count: number; bytes: number; ms: number; failed: number }
+  /**
+   * The machines an executor plugin ran tasks on, with what each did
+   * (`TaskExecutor.machines`); a task's `where` names one. Absent when no
+   * executor reports any. Additive.
+   */
+  machines?: readonly MachineReport[]
 }
 
 /** One stage of a run, a wall window in epoch ms. */
@@ -305,6 +311,7 @@ export function assembleRunSummary(
     abortedCount: number
     stages?: readonly RunStage[]
     uploads?: { count: number; bytes: number; ms: number; failed: number }
+    machines?: readonly MachineReport[]
   },
 ): RunSummaryRecord {
   let failedCount = 0
@@ -343,6 +350,9 @@ export function assembleRunSummary(
     ...(timing.uploads !== undefined && timing.uploads.count + timing.uploads.failed > 0
       ? { uploads: { ...timing.uploads } }
       : {}),
+    ...(timing.machines !== undefined && timing.machines.length > 0
+      ? { machines: timing.machines }
+      : {}),
   }
 }
 
@@ -400,8 +410,19 @@ export interface TelemetrySource {
    * Sample this task's process tree every `SAMPLE_MS` until the returned
    * function is called, the root exits, or the run ends. Present only when
    * a sink wants `task.sample`: nobody asking costs no timer and no read.
+   * The returned stop answers what the samples saw, for the run history.
    */
-  readonly track?: (taskId: string, pid: number) => () => void
+  readonly track?: (taskId: string, pid: number) => () => TreeLoad | undefined
+}
+
+/**
+ * What a tracked task's samples saw: the most cores one interval between
+ * looks burned, and the mean resident memory over the looks. Undefined
+ * when no look landed (a task shorter than `SAMPLE_MS`).
+ */
+export interface TreeLoad {
+  peakCores: number
+  avgRssBytes: number
 }
 
 /** How often a running task's process tree is sampled. */
@@ -476,10 +497,18 @@ export function createTelemetrySource(args: {
   const wantsLog = sinks.some((s) => (s.wants ?? DEFAULT_KINDS).includes('task.log'))
   const wantsSample = sinks.some((s) => (s.wants ?? DEFAULT_KINDS).includes('task.sample'))
 
-  // taskId → the pid of its running root. One timer for every task, alive
-  // only while one runs; a tick still reading when the next is due is not
-  // doubled.
-  const tracked = new Map<string, number>()
+  // taskId → its running root and what the looks at it saw. One timer for
+  // every task, alive only while one runs; a tick still reading when the
+  // next is due is not doubled.
+  interface Tracked {
+    pid: number
+    lastTs: number
+    lastCpuMs: number
+    peakCores: number
+    rssSum: number
+    looks: number
+  }
+  const tracked = new Map<string, Tracked>()
   const every = args.every ?? everyInterval
   let stopEvery: (() => void) | undefined
   let sampling = false
@@ -488,8 +517,8 @@ export function createTelemetrySource(args: {
     stopEvery?.()
     stopEvery = undefined
   }
-  const untrack = (taskId: string, pid: number): void => {
-    if (tracked.get(taskId) === pid) tracked.delete(taskId)
+  const untrack = (taskId: string, t: Tracked): void => {
+    if (tracked.get(taskId) === t) tracked.delete(taskId)
     if (tracked.size === 0) stopTimer()
   }
   const tick = async (): Promise<void> => {
@@ -497,15 +526,23 @@ export function createTelemetrySource(args: {
     sampling = true
     try {
       const entries = [...tracked]
-      const usage = await sampleTrees(entries.map(([, pid]) => pid))
+      const usage = await sampleTrees(entries.map(([, t]) => t.pid))
       const ts = Date.now()
-      for (const [taskId, pid] of entries) {
-        if (ended || tracked.get(taskId) !== pid) continue
-        const u = usage.get(pid)
+      for (const [taskId, t] of entries) {
+        if (ended || tracked.get(taskId) !== t) continue
+        const u = usage.get(t.pid)
         if (u === undefined) {
-          untrack(taskId, pid)
+          untrack(taskId, t)
           continue
         }
+        // A descendant that exited takes its CPU out of the live sum, so an
+        // interval can read negative: it says nothing of the peak.
+        const ms = ts - t.lastTs
+        if (ms > 0) t.peakCores = Math.max(t.peakCores, (u.cpuMs - t.lastCpuMs) / ms)
+        t.lastTs = ts
+        t.lastCpuMs = u.cpuMs
+        t.rssSum += u.rssBytes
+        t.looks++
         deliver({
           v: TELEMETRY_SCHEMA_VERSION,
           kind: 'task.sample',
@@ -522,11 +559,17 @@ export function createTelemetrySource(args: {
       sampling = false
     }
   }
-  const track = (taskId: string, pid: number): (() => void) => {
-    if (ended) return () => {}
-    tracked.set(taskId, pid)
+  const track = (taskId: string, pid: number): (() => TreeLoad | undefined) => {
+    if (ended) return () => undefined
+    const t: Tracked = { pid, lastTs: Date.now(), lastCpuMs: 0, peakCores: 0, rssSum: 0, looks: 0 }
+    tracked.set(taskId, t)
     stopEvery ??= every(SAMPLE_MS, tick)
-    return () => untrack(taskId, pid)
+    return () => {
+      untrack(taskId, t)
+      return t.looks === 0
+        ? undefined
+        : { peakCores: t.peakCores, avgRssBytes: Math.round(t.rssSum / t.looks) }
+    }
   }
 
   function deliver(record: TelemetryRecord): void {