@vzn/vx 0.0.517 → 0.0.519

package/README.md

@@ -145,7 +145,7 @@ Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
 | [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
 | [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
 | [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
-| [`@vzn/vx-github`](packages/vx-github)                     | GitHub Actions job summary and Checks API                                     |
+| [`@vzn/vx-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
 | [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
 | [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.517",
+  "version": "0.0.519",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.517",
-    "@vzn/vx-linux-arm64": "0.0.517",
-    "@vzn/vx-darwin-x64": "0.0.517",
-    "@vzn/vx-darwin-arm64": "0.0.517"
+    "@vzn/vx-linux-x64": "0.0.519",
+    "@vzn/vx-linux-arm64": "0.0.519",
+    "@vzn/vx-darwin-x64": "0.0.519",
+    "@vzn/vx-darwin-arm64": "0.0.519"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/exec/executor.ts

@@ -152,6 +152,13 @@ export interface ExecuteRequest {
   readonly signal?: AbortSignal
   /** See `RunOptions.liveChildren`: the run's SIGINT/SIGTERM registry. */
   readonly liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /**
+   * An executor that runs the command as a process on THIS machine calls
+   * this with its pid once spawned, so a telemetry plugin can sample the
+   * process tree's CPU and memory while it runs. Absent when nobody samples;
+   * an executor that runs elsewhere never calls it.
+   */
+  readonly onSpawn?: (pid: number) => void
   readonly sandbox?: ExecuteSandbox
   /**
    * The task holds vx's terminal (`exec.interactive` on a TTY): its stdin,

package/src/exec/index.ts

@@ -45,6 +45,7 @@ export {
 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 {
   assertExecuteResult,
   executorFallback,

package/src/exec/local-executor.ts

@@ -42,6 +42,7 @@ export function localExecutor(): TaskExecutor {
         onStderr: req.onStderr,
         capture: req.capture,
         ...(req.liveChildren !== undefined ? { liveChildren: req.liveChildren } : {}),
+        ...(req.onSpawn !== undefined ? { onSpawn: req.onSpawn } : {}),
         ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
       }
       if (req.sandbox === undefined) {

package/src/exec/proc-sample.ts

@@ -0,0 +1,151 @@
+// What a running task's process tree uses right now: CPU time and resident
+// memory summed over a root pid and every descendant. `resourceUsage()`
+// answers only at exit, so a task's curve needs a look while it runs.
+//
+// A tree, not a process group: a sandboxed task runs under bwrap in a
+// session of its own, so its processes carry another group, but each still
+// has its parent. A process that left the tree (re-parented to init) is not
+// counted; nor is the CPU of a descendant that already exited.
+
+import { readdir, readFile } from 'node:fs/promises'
+import { procfsIsOwn } from '../util/index.js'
+
+export interface TreeUsage {
+  /** CPU time of the live tree, user + system, in ms. */
+  cpuMs: number
+  /** Resident memory of the live tree, in bytes. */
+  rssBytes: number
+}
+
+interface Proc {
+  ppid: number
+  cpuMs: number
+  /** Resident KiB when the table carries it; Linux reads it per tree member. */
+  rssKiB?: number
+}
+
+/**
+ * Linux's `/proc/<pid>/stat` counts CPU in USER_HZ ticks, fixed at 100 by
+ * the ABI on every architecture; `tests/proc-sample.test.ts` pins it by
+ * burning a known span and reading it back.
+ */
+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>> {
+  const out = new Map<number, TreeUsage>()
+  if (roots.length === 0) return out
+  const table = process.platform === 'linux' ? await linuxTable() : await psTable()
+  if (table === undefined) return out
+  const children = new Map<number, number[]>()
+  for (const [pid, p] of table) {
+    const list = children.get(p.ppid)
+    if (list === undefined) children.set(p.ppid, [pid])
+    else list.push(pid)
+  }
+  for (const root of roots) {
+    if (!table.has(root)) continue
+    const tree: number[] = []
+    const stack = [root]
+    while (stack.length > 0) {
+      const pid = stack.pop()!
+      tree.push(pid)
+      for (const c of children.get(pid) ?? []) stack.push(c)
+    }
+    let cpuMs = 0
+    let rssKiB = 0
+    const rss = await Promise.all(tree.map((pid) => table.get(pid)!.rssKiB ?? linuxRssKiB(pid)))
+    for (const [i, pid] of tree.entries()) {
+      cpuMs += table.get(pid)!.cpuMs
+      rssKiB += rss[i]!
+    }
+    out.set(root, { cpuMs, rssBytes: rssKiB * 1024 })
+  }
+  return out
+}
+
+async function linuxTable(): Promise<Map<number, Proc> | undefined> {
+  // Another namespace's /proc is a table of strangers: no answer beats a wrong one.
+  if (!procfsIsOwn()) return undefined
+  let entries: string[]
+  try {
+    entries = await readdir('/proc')
+  } catch {
+    return undefined
+  }
+  const table = new Map<number, Proc>()
+  await Promise.all(
+    entries.map(async (entry) => {
+      const first = entry.charCodeAt(0)
+      if (first < 48 || first > 57) return
+      let stat: string
+      try {
+        stat = await readFile(`/proc/${entry}/stat`, 'utf8')
+      } catch {
+        return // exited between the listing and the read
+      }
+      // `<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(' ')
+      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,
+      })
+    }),
+  )
+  return table
+}
+
+/** `VmRSS` carries its unit (kB); 0 for a process gone or a kernel thread. */
+async function linuxRssKiB(pid: number): Promise<number> {
+  try {
+    const status = await readFile(`/proc/${pid}/status`, 'utf8')
+    const m = /^VmRSS:\s+(\d+) kB$/m.exec(status)
+    return m === null ? 0 : Number(m[1])
+  } catch {
+    return 0
+  }
+}
+
+/** macOS (and any non-Linux): one `ps` for the whole table. */
+async function psTable(): Promise<Map<number, Proc> | undefined> {
+  let text: string
+  try {
+    const ps = Bun.spawn(['ps', '-A', '-o', 'pid=,ppid=,rss=,time='], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    text = await new Response(ps.stdout).text()
+    if ((await ps.exited) !== 0) return undefined
+  } catch {
+    return undefined
+  }
+  const table = new Map<number, Proc>()
+  for (const line of text.split('\n')) {
+    const f = line.trim().split(/\s+/)
+    if (f.length < 4) continue
+    const cpuMs = psTimeMs(f[3]!)
+    if (cpuMs === undefined) continue
+    table.set(Number(f[0]), { ppid: Number(f[1]), rssKiB: Number(f[2]), cpuMs })
+  }
+  return table
+}
+
+/** `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths. */
+export function psTimeMs(s: string): number | undefined {
+  const dash = s.indexOf('-')
+  const days = dash === -1 ? 0 : Number(s.slice(0, dash))
+  const parts = s
+    .slice(dash + 1)
+    .split(':')
+    .map(Number)
+  if (parts.length < 2 || parts.some((n) => !Number.isFinite(n)) || !Number.isFinite(days)) {
+    return undefined
+  }
+  let seconds = 0
+  for (const n of parts) seconds = seconds * 60 + n
+  return Math.round((days * 86_400 + seconds) * 1000)
+}

package/src/exec/runner.ts

@@ -87,6 +87,8 @@ export interface RunOptions {
    * handler can SIGTERM everything still alive mid-run.
    */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /** Told the child's pid once it is spawned (telemetry samples its tree). */
+  onSpawn?: (pid: number) => void
   /**
    * Hand the child vx's own stdin, stdout and stderr (`exec.interactive` on
    * a TTY). Nothing passes through vx: the callbacks hear nothing and the
@@ -632,6 +634,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   void consumeChunks(child.stderr, true)
 
   opts.liveChildren?.add(child)
+  opts.onSpawn?.(child.pid)
 
   // Readiness deadline. Reject FIRST so the failure reads as a
   // timeout, then SIGTERM — the exit handler's later reject is a
@@ -738,6 +741,7 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   }
 
   opts.liveChildren?.add(proc)
+  opts.onSpawn?.(proc.pid)
   const timeout = armTimeout(proc, opts.timeoutMs)
   const ac = new AbortController()
   const streams = Promise.all([

package/src/exec/sandbox-runtime.ts

@@ -808,6 +808,8 @@ export interface SandboxedRunArgs {
   onStderr?: (chunk: string) => void
   /** See `RunOptions.liveChildren` — same contract for sandboxed spawns. */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /** See `RunOptions.onSpawn`. */
+  onSpawn?: (pid: number) => void
   /** `ExecuteRequest.signal`: once aborted, the tracer retry spawns nothing. */
   signal?: AbortSignal
   /** See `RunOptions.timeoutMs` — SIGTERM the child after this many ms. */
@@ -1836,6 +1838,7 @@ async function runSandboxedOnce(
   }
 
   args.liveChildren?.add(proc)
+  args.onSpawn?.(proc.pid)
   const timeout = armTimeout(proc, args.timeoutMs)
   const ac = new AbortController()
   // The unfinished last line of stderr, and whether a line was strace's.

package/src/orchestrator/execute-task.ts

@@ -145,6 +145,8 @@ export interface ExecuteArgs {
    * SIGTERMs whatever is in here.
    */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
+  /** Sample a spawned task's process tree (`TelemetrySource.track`); absent when nobody samples. */
+  track?: (taskId: string, pid: number) => () => void
   /**
    * Run-level retry default (`--retry <n>` / `RunOptions.retries`).
    * Explicit `exec.retries` wins, including an explicit 0. Threaded as
@@ -376,6 +378,9 @@ async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutcome> {
     onStdout: serverOut ? (chunk) => serverOut.push(chunk) : (chunk) => log.taskStdout(node, chunk),
     onStderr: serverErr ? (chunk) => serverErr.push(chunk) : (chunk) => log.taskStderr(node, chunk),
     ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
+    ...(args.track !== undefined
+      ? { onSpawn: (pid: number) => void args.track!(node.id, pid) }
+      : {}),
     ...(signalChannel ? { signalChannel } : {}),
     ...(args.terminal === true ? { terminal: true } : {}),
   }
@@ -953,6 +958,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         unlistenStop?.()
         unlistenStop = undefined
         flushMasked()
+        untrack?.()
+        untrack = undefined
       })
     endExec()
     if (secrets !== null)
@@ -1076,6 +1083,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // and what the cache keeps of it (L-11); null when there are none.
   const secrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
   let flushMasked = (): void => {}
+  // The sampling of the attempt's process tree, stopped once it settles.
+  let untrack: (() => void) | undefined
   // The entry's command is shown by `vx why` and sent with the entry to a
   // remote cache: a value a config interpolated stays out of both.
   const storedCommand = secrets?.mask(step.command) ?? step.command
@@ -1155,6 +1164,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       onStdout: out ? (chunk) => out.push(chunk) : (chunk) => log.taskStdout(node, chunk),
       onStderr: err ? (chunk) => err.push(chunk) : (chunk) => log.taskStderr(node, chunk),
       ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
+      ...(args.track !== undefined
+        ? {
+            onSpawn: (pid: number) => {
+              untrack?.()
+              untrack = args.track!(node.id, pid)
+            },
+          }
+        : {}),
       signal: requestSignal(),
       ...(effectiveTimeout !== undefined ? { timeoutMs: effectiveTimeout } : {}),
       ...(inputs !== undefined ? { inputs } : {}),

package/src/orchestrator/run.ts

@@ -938,6 +938,7 @@ async function runOnBus(
         runStartHrTimeNs,
         persistentRegistry,
         liveChildren,
+        ...(telemetry?.track !== undefined ? { track: telemetry.track } : {}),
         gitFilesCache,
         hashCache,
         ...(probe !== undefined ? { preProbed: probe } : {}),

package/src/orchestrator/telemetry-host.ts

@@ -30,6 +30,8 @@ export interface TelemetryHandle {
   flush(): Promise<void>
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
+  /** Sample a running task's process tree; see `TelemetrySource.track`. */
+  readonly track?: (taskId: string, pid: number) => () => void
 }
 
 /** Reject anything that is not sink-shaped, naming what arrived. */
@@ -117,5 +119,6 @@ export async function subscribeTelemetry(
     emitSummary: (summary) => source.emitSummary(summary),
     flush: () => source.flush(),
     dispose,
+    ...(source.track !== undefined ? { track: source.track } : {}),
   }
 }

package/src/orchestrator/telemetry.ts

@@ -16,6 +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 type { TaskOutcome, TaskStatus } from '../graph/index.js'
 import { maskedCommand, settleWithin, teardownTimeoutMs } from '../util/index.js'
 import type { RunEvent, RunEventSubscriber } from './events.js'
@@ -227,6 +228,17 @@ export type TelemetryRecord =
       chunk: string
       ts: number
     }
+  | {
+      v: number
+      kind: 'task.sample'
+      runId: string
+      taskId: string
+      ts: number
+      /** CPU time of the task's live process tree so far, in ms. */
+      cpuMs: number
+      /** Resident memory of the task's live process tree, in bytes. */
+      rssBytes: number
+    }
   | ({ v: number; kind: 'task.end'; runId: string; ts: number } & TaskTelemetry)
   | { v: number; kind: 'run.end'; runId: string; ts: number }
 
@@ -370,8 +382,17 @@ export interface TelemetrySource {
   emitSummary(summary: RunSummaryRecord): void
   /** Await every sink's `flush()` (each crash-isolated, all time-bounded). */
   flush(): Promise<void>
+  /**
+   * 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.
+   */
+  readonly track?: (taskId: string, pid: number) => () => void
 }
 
+/** How often a running task's process tree is sampled. */
+const SAMPLE_MS = 1000
+
 const DEFAULT_KINDS: ReadonlyArray<TelemetryRecord['kind']> = [
   'run.start',
   'task.start',
@@ -426,6 +447,62 @@ export function createTelemetrySource(args: {
   // Precompute which sinks want each kind, so per-event fan-out is a plain
   // array walk with no per-record `wants` scanning.
   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>()
+  let timer: ReturnType<typeof setInterval> | undefined
+  let sampling = false
+  let ended = false
+  const stopTimer = (): void => {
+    if (timer !== undefined) clearInterval(timer)
+    timer = undefined
+  }
+  const untrack = (taskId: string, pid: number): void => {
+    if (tracked.get(taskId) === pid) tracked.delete(taskId)
+    if (tracked.size === 0) stopTimer()
+  }
+  const tick = async (): Promise<void> => {
+    if (sampling) return
+    sampling = true
+    try {
+      const entries = [...tracked]
+      const usage = await sampleTrees(entries.map(([, pid]) => pid))
+      const ts = Date.now()
+      for (const [taskId, pid] of entries) {
+        if (ended || tracked.get(taskId) !== pid) continue
+        const u = usage.get(pid)
+        if (u === undefined) {
+          untrack(taskId, pid)
+          continue
+        }
+        deliver({
+          v: TELEMETRY_SCHEMA_VERSION,
+          kind: 'task.sample',
+          runId,
+          taskId,
+          ts,
+          cpuMs: u.cpuMs,
+          rssBytes: u.rssBytes,
+        })
+      }
+    } catch {
+      // A failed look is a missing point, never a broken run.
+    } finally {
+      sampling = false
+    }
+  }
+  const track = (taskId: string, pid: number): (() => void) => {
+    if (ended) return () => {}
+    tracked.set(taskId, pid)
+    if (timer === undefined) {
+      timer = setInterval(() => void tick(), SAMPLE_MS)
+      timer.unref()
+    }
+    return () => untrack(taskId, pid)
+  }
 
   function deliver(record: TelemetryRecord): void {
     for (const sink of sinks) {
@@ -502,6 +579,9 @@ export function createTelemetrySource(args: {
       case 'run:status':
         return // status lines are terminal-rendering noise, not telemetry
       case 'run:end':
+        ended = true
+        tracked.clear()
+        stopTimer()
         deliver({ v: TELEMETRY_SCHEMA_VERSION, kind: 'run.end', runId, ts })
         return
     }
@@ -509,6 +589,7 @@ export function createTelemetrySource(args: {
 
   return {
     subscriber,
+    ...(wantsSample ? { track } : {}),
     emitSummary(summary: RunSummaryRecord): void {
       for (const sink of sinks) {
         if (disabled.has(sink) || sink.onRunSummary === undefined) continue