@vzn/vx 0.0.519 → 0.0.521

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.519",
+  "version": "0.0.521",
   "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.519",
-    "@vzn/vx-linux-arm64": "0.0.519",
-    "@vzn/vx-darwin-x64": "0.0.519",
-    "@vzn/vx-darwin-arm64": "0.0.519"
+    "@vzn/vx-linux-x64": "0.0.521",
+    "@vzn/vx-linux-arm64": "0.0.521",
+    "@vzn/vx-darwin-x64": "0.0.521",
+    "@vzn/vx-darwin-arm64": "0.0.521"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/graph/scheduler.ts

@@ -139,6 +139,8 @@ export interface TaskOutcome {
    * flaky detection reads it off the outcome stream.
    */
   attempts?: number
+  /** The attempts that failed and were run again, in order: when each ended (epoch ms) and how. */
+  failedAttempts?: readonly { endedAt: number; exitCode: number; timedOut?: true }[]
   /**
    * Set when this run proved the task flaky: its key holds both outcomes on
    * record (this run's included) or it needed a retry. Its row carries it.

package/src/orchestrator/execute-task.ts

@@ -1083,6 +1083,7 @@ 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 => {}
+  const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
   // 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
@@ -1139,6 +1140,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
 
     if (effectiveExitCode === 0 || attempt >= maxAttempts) break
+    failedAttempts.push({
+      endedAt: Date.now(),
+      exitCode: effectiveExitCode,
+      ...(result.timedOut === true ? { timedOut: true as const } : {}),
+    })
     log.taskStderr(
       node,
       `vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after ${result.timedOut === true ? 'a timeout' : `exit ${effectiveExitCode}`}\n`,
@@ -1354,6 +1360,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     durationMs: spentMs,
     hash,
     ...(attempt > 1 ? { attempts: attempt } : {}),
+    ...(failedAttempts.length > 0 ? { failedAttempts } : {}),
     ...(unkeyed ? { unkeyed: true as const } : {}),
     ...(result.timedOut === true && effectiveExitCode !== 0 ? { timedOut: true as const } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),

package/src/orchestrator/prepare.ts

@@ -9,7 +9,7 @@
 
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { mark, nearest, UserError } from '../util/index.js'
+import { beginRun, mark, nearest, UserError } from '../util/index.js'
 import {
   Cache,
   noteSchemaReset,
@@ -182,6 +182,7 @@ export interface PreparedRun {
  * empty plan).
  */
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
+  beginRun()
   mark('startup')
   // The root manifest is read once for the root, the globs and the
   // fingerprint. A watch cycle is a new run and reads it afresh.

package/src/orchestrator/run.ts

@@ -26,6 +26,7 @@ import {
 } from '../graph/index.js'
 import {
   mark,
+  stageTimes,
   killGraceMs,
   MAX_TIMEOUT_MS,
   parseDuration,
@@ -755,6 +756,7 @@ async function runOnBus(
         { workspaceRoot, cacheDir, warn: (m: string) => log.status(m) },
         runContextRecord,
         options.telemetrySinks,
+        nodes,
       )
     }
 
@@ -1202,6 +1204,7 @@ async function runOnBus(
         totalDurationMs: Math.round(totalMs),
         exitOk: ok,
         abortedCount: list.filter((o) => o.status === 'aborted' && !isGroupTask(o.node)).length,
+        stages: stageTimes(),
       })
       telemetry.emitSummary(summary)
       await telemetry.flush()

package/src/orchestrator/telemetry-host.ts

@@ -12,6 +12,7 @@
 // See docs/design/observability-architecture-2026-06.md §1, §3.
 
 import type { EventBus } from './events.js'
+import type { TaskNode } from '../graph/index.js'
 import type {
   RunContextRecord,
   RunSummaryRecord,
@@ -70,6 +71,7 @@ export async function subscribeTelemetry(
   ctx: TelemetryContext,
   run: RunContextRecord,
   extraSinks?: readonly TelemetrySink[],
+  nodes?: ReadonlyMap<string, TaskNode>,
 ): Promise<TelemetryHandle | undefined> {
   const sinks: TelemetrySink[] = extraSinks === undefined ? [] : [...extraSinks]
   const owners = new Map<TelemetrySink, string>()
@@ -111,7 +113,13 @@ export async function subscribeTelemetry(
 
   if (sinks.length === 0) return undefined
 
-  const source = createTelemetrySource({ sinks, run, warn: (m) => ctx.warn(m), owners })
+  const source = createTelemetrySource({
+    sinks,
+    run,
+    warn: (m) => ctx.warn(m),
+    owners,
+    ...(nodes !== undefined ? { nodes } : {}),
+  })
   // The bus's unsubscribe is idempotent, so it is the handle's dispose as
   // is (a once-flag here survived item 654).
   const dispose = bus.subscribe(source.subscriber)

package/src/orchestrator/telemetry.ts

@@ -17,7 +17,7 @@
 // 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 { isGroupTask, type TaskNode, type TaskOutcome, type TaskStatus } from '../graph/index.js'
 import { maskedCommand, settleWithin, teardownTimeoutMs } from '../util/index.js'
 import type { RunEvent, RunEventSubscriber } from './events.js'
 
@@ -146,6 +146,15 @@ export interface RunContextRecord {
   tags: Readonly<Record<string, string>>
 }
 
+/** One attempt of a retried task that failed and was run again. */
+export interface FailedAttempt {
+  /** When the attempt ended, epoch ms. */
+  endedAt: number
+  exitCode: number
+  /** vx's own `timeout` ended it. */
+  timedOut?: true
+}
+
 /** Denormalized per-task analytics — shared by the streaming `task.end`
  *  record and the per-run summary's `tasks[]`. */
 export interface TaskTelemetry {
@@ -181,6 +190,19 @@ export interface TaskTelemetry {
   sandboxViolations?: number
   /** On a failed persistent task: why it never became ready. `exitCode` is the child's own when it exited. Additive. */
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /** On a task that retried: each attempt that failed before the last, in order. Additive. */
+  failedAttempts?: readonly FailedAttempt[]
+  /** On a task proved flaky this run: its key's passes and failures on record. Additive. */
+  flaky?: { passes: number; failures: number }
+  /** On a sandboxed task: the violation lines themselves, one per denial. Additive. */
+  sandboxViolationLines?: readonly string[]
+  /** On a cache hit: how long the run that stored the entry took — the time this hit saved. Additive. */
+  storedDurationMs?: number
+  /** On a cache hit: the CPU and peak memory of the run that stored it. Additive. */
+  storedCpuMs?: number
+  storedPeakRssBytes?: number
+  /** How long an `admit` policy held the task once it was ready. Additive. */
+  admissionHeldMs?: number
   /**
    * On a cache hit: whether outputs were written this run (`true`) or the
    * disk already matched the entry and nothing was restored (`false`, an
@@ -217,6 +239,12 @@ export type TelemetryRecord =
       project: string
       task: string
       command?: string
+      /**
+       * The tasks with a command this one waits on: its direct dependencies,
+       * a group's seen through to the tasks with a command behind it.
+       * Additive.
+       */
+      dependsOn?: readonly string[]
       ts: number
     }
   | {
@@ -276,6 +304,19 @@ export interface RunSummaryRecord {
   restoredRemoteCount: number
   exitOk: boolean
   tasks: readonly TaskTelemetry[]
+  /**
+   * The run's stages as `VX_TIMING` marks them (startup, load configs,
+   * classify + probe, run graph, …), each a wall window in epoch ms. The
+   * stages ahead of the run lock end before `startedAt`. Additive.
+   */
+  stages?: readonly RunStage[]
+}
+
+/** One stage of a run, a wall window in epoch ms. */
+export interface RunStage {
+  name: string
+  startedAt: number
+  endedAt: number
 }
 
 /**
@@ -298,6 +339,7 @@ export function assembleRunSummary(
     totalDurationMs: number
     exitOk: boolean
     abortedCount: number
+    stages?: readonly RunStage[]
   },
 ): RunSummaryRecord {
   let failedCount = 0
@@ -332,6 +374,7 @@ export function assembleRunSummary(
     restoredRemoteCount,
     exitOk: timing.exitOk,
     tasks,
+    ...(timing.stages !== undefined && timing.stages.length > 0 ? { stages: timing.stages } : {}),
   }
 }
 
@@ -418,6 +461,8 @@ export function createTelemetrySource(args: {
   warn?: (message: string) => void
   /** What a sink with no `name` of its own is called: its plugin's (the host's map). */
   owners?: ReadonlyMap<TelemetrySink, string>
+  /** The run's task graph, to see a group dependency through to the tasks behind it. */
+  nodes?: ReadonlyMap<string, TaskNode>
 }): TelemetrySource {
   const { sinks, run, warn } = args
   const runId = run.runId
@@ -547,6 +592,8 @@ export function createTelemetrySource(args: {
         }
         if (node.config.exec.command !== undefined)
           rec.command = maskedCommand(node.config.exec.command, node.config.exec.env)
+        const deps = commandDeps(node, args.nodes)
+        if (deps.length > 0) rec.dependsOn = deps
         deliver(rec)
         return
       }
@@ -637,6 +684,23 @@ export function createTelemetrySource(args: {
   }
 }
 
+/** `node`'s dependencies with a command; a group is seen through, once each. */
+function commandDeps(node: TaskNode, nodes: ReadonlyMap<string, TaskNode> | undefined): string[] {
+  if (nodes === undefined) return node.deps
+  const out: string[] = []
+  const seen = new Set<string>()
+  const stack = [...node.deps].reverse()
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (seen.has(id)) continue
+    seen.add(id)
+    const dep = nodes.get(id)
+    if (dep !== undefined && isGroupTask(dep)) stack.push(...[...dep.deps].reverse())
+    else out.push(id)
+  }
+  return out
+}
+
 /**
  * The one projection of an outcome into `TaskTelemetry`, for the streaming
  * `task.end` record and the summary's `tasks[]` alike. Two copies drifted:
@@ -664,6 +728,15 @@ export function taskTelemetryOf(o: TaskOutcome): TaskTelemetry {
   if (o.timedOut === true) t.timedOut = true
   if (o.sandboxViolations !== undefined) t.sandboxViolations = o.sandboxViolations
   if (o.notReady !== undefined) t.notReady = o.notReady
+  if (o.failedAttempts !== undefined) t.failedAttempts = o.failedAttempts
+  if (o.flaky !== undefined) t.flaky = o.flaky
+  if (o.sandboxViolationLines !== undefined && o.sandboxViolationLines.length > 0) {
+    t.sandboxViolationLines = o.sandboxViolationLines
+  }
+  if (o.storedDurationMs !== undefined) t.storedDurationMs = o.storedDurationMs
+  if (o.storedCpuMs !== undefined) t.storedCpuMs = o.storedCpuMs
+  if (o.storedPeakRssBytes !== undefined) t.storedPeakRssBytes = o.storedPeakRssBytes
+  if (o.admissionHeldMs !== undefined) t.admissionHeldMs = o.admissionHeldMs
   if (isCacheHit(o.status)) t.restored = o.restored === true
   if (o.wallclockStartNs !== undefined) t.wallclockStartNs = o.wallclockStartNs.toString()
   if (o.wallclockEndNs !== undefined) t.wallclockEndNs = o.wallclockEndNs.toString()

package/src/util/index.ts

@@ -18,7 +18,15 @@ export {
   OUT_OF_FDS_HINT,
 } from './errors.js'
 export { xxh3, xxh3hex } from './hash.js'
-export { mark, printTimings, restartTimings, span } from './timing.js'
+export {
+  beginRun,
+  mark,
+  printTimings,
+  restartTimings,
+  span,
+  stageTimes,
+  type StageTime,
+} from './timing.js'
 export { clampInt, formatElapsed, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
 export {
   asTrees,

package/src/util/timing.ts

@@ -2,20 +2,55 @@
 //
 // The CPU profiler attributes a tight loop's cost unreliably and hides
 // where an `await` waited; a stage table answers "where did the warm run
-// go?" directly, and costs one boolean check per mark when off. Marks are
-// cumulative from this module's load — process start and the imports ahead
-// of it sit outside the table; the table shows each stage's own share.
+// go?" directly. Marks are cumulative from this module's load — process
+// start and the imports ahead of it sit outside the table; the table shows
+// each stage's own share. Stage marks are kept whether or not the table
+// prints (a push per stage, ~15 a run): a telemetry sink draws them as
+// spans (`stageTimes`). The per-call `span`s stay off unless enabled.
 
 const enabled = process.env.VX_TIMING !== undefined && process.env.VX_TIMING !== ''
 let t0 = Bun.nanoseconds()
+// The wall clock at t0, read then: `performance.timeOrigin` plus the
+// monotonic clock drifted 34 ms from `Date.now()` on macOS CI, so stages
+// drawn from it sat outside the run they belong to.
+let wall0 = Date.now()
 const marks: Array<[label: string, ns: number]> = []
 
-/** Record the end of a stage. No-op unless `VX_TIMING` is set. */
+let begun = false
+
+/**
+ * A run begins. The process's first counts from this module's load, so
+ * `startup` holds the imports; a later one in the same process (an
+ * embedder's second `run()`) starts a table of its own, or its stages
+ * would follow the last run's and its `startup` would hold the idle between.
+ */
+export function beginRun(): void {
+  if (begun) restartTimings()
+  begun = true
+}
+
+/** Record the end of a stage. */
 export function mark(label: string): void {
-  if (!enabled) return
   marks.push([label, Bun.nanoseconds() - t0])
 }
 
+/** One stage's wall window, in epoch ms. */
+export interface StageTime {
+  name: string
+  startedAt: number
+  endedAt: number
+}
+
+/** The stages marked so far, each from the previous mark's end (the first from this module's load). */
+export function stageTimes(): StageTime[] {
+  let prev = 0
+  return marks.map(([name, ns]) => {
+    const stage = { name, startedAt: wall0 + prev / 1e6, endedAt: wall0 + ns / 1e6 }
+    prev = ns
+    return stage
+  })
+}
+
 const spans = new Map<string, [count: number, ns: number]>()
 const noop = (): void => {}
 
@@ -25,8 +60,8 @@ const noop = (): void => {}
  * its first stage counted the idle wait before it.
  */
 export function restartTimings(): void {
-  if (!enabled) return
   t0 = Bun.nanoseconds()
+  wall0 = Date.now()
   marks.length = 0
   spans.clear()
 }