@vzn/vx 0.0.526 → 0.0.528

package/package.json

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

package/src/graph/index.ts

@@ -11,6 +11,7 @@ export {
 export {
   type ContinueMode,
   deadServerBehind,
+  type InputChanges,
   RestoreDemoted,
   runGraph,
   type TaskOutcome,

package/src/graph/scheduler.ts

@@ -36,6 +36,14 @@ export type TaskStatus =
   // are partial.
   | 'aborted'
 
+/** What moved in a missed task's key since the last entry saved for it. */
+export interface InputChanges {
+  /** How many components changed, appeared or went. 0: the same key, its entry gone. */
+  count: number
+  /** The first of them, by kind then name. */
+  first: readonly { kind: string; name: string; change: 'changed' | 'added' | 'removed' }[]
+}
+
 export interface TaskOutcome {
   node: TaskNode
   status: TaskStatus
@@ -69,6 +77,20 @@ export interface TaskOutcome {
    * stream and the summary footer show it.
    */
   admissionHeldMs?: number
+  /**
+   * How long this task waited ready (its deps done, or none to wait on)
+   * before it was dispatched: a full worker pool's wait, plus any
+   * `admissionHeldMs`. Absent when it started within the millisecond and
+   * on a task that never ran.
+   */
+  queuedMs?: number
+  /** On a cacheable task that ran: how many files its key read. */
+  inputFiles?: number
+  /**
+   * On a cacheable task that ran: what its key changed since the last entry
+   * saved for it. Only when a telemetry sink asked, and the cache holds one.
+   */
+  inputChanges?: InputChanges
   /** v11 analytics: CPU time + peak RSS for this task's child process. */
   cpuMs?: number
   peakRssBytes?: number
@@ -439,9 +461,14 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   // decrements still happen (in finishOne) but never re-enqueue it.
   // Everything else enqueues on the exec-tier the moment its deps
   // complete.
+  // When each queued id became ready; dispatch takes it out.
+  const readyAt = new Map<string, number>()
+  const startedAt = Date.now()
   for (const node of nodes.values()) {
     if (restoreTier?.has(node.id)) restoreReady.push(node.id)
     else if (node.deps.length === 0) execReady.push(node.id)
+    else continue
+    readyAt.set(node.id, startedAt)
   }
 
   let active = 0
@@ -603,7 +630,10 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         // don't wait on deps); one that finished early releases its own
         // dependents now. Only an exec-tier dependent is enqueued.
         if (heldRelease.delete(d)) release(d)
-        else if (!inRestoreTier(d)) execReady.push(d)
+        else if (!inRestoreTier(d)) {
+          execReady.push(d)
+          readyAt.set(d, Date.now())
+        }
       }
     }
 
@@ -741,6 +771,8 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
           continue
         }
 
+        const queuedMs = Date.now() - (readyAt.get(id) ?? Date.now())
+        readyAt.delete(id)
         const leave = admit(id)
         // Listed as running on dispatch, so the policy's next ask in this
         // tick sees it; the completion callbacks unlist it.
@@ -749,7 +781,13 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         const heldMs = since === undefined ? 0 : Math.max(1, Date.now() - since)
         if (since !== undefined) heldSince.delete(id)
         const withHold = (o: TaskOutcome): TaskOutcome =>
-          heldMs > 0 ? { ...o, admissionHeldMs: heldMs } : o
+          heldMs === 0 && queuedMs === 0
+            ? o
+            : {
+                ...o,
+                ...(heldMs > 0 ? { admissionHeldMs: heldMs } : {}),
+                ...(queuedMs > 0 ? { queuedMs } : {}),
+              }
         // Crash-isolated observer hook — a throwing onStart must not abort
         // the dispatch loop (it would strand the tick with the slot held).
         // A demoted task's second dispatch is the same task, already started.
@@ -799,7 +837,10 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               leave()
               untrack()
               demoted.add(id)
-              if (pending.get(id) === 0) execReady.push(id)
+              if (pending.get(id) === 0) {
+                execReady.push(id)
+                readyAt.set(id, Date.now())
+              }
               tick()
               return
             }

package/src/orchestrator/events.ts

@@ -7,7 +7,7 @@
 // stall task exec. See docs/design/event-stream-2026-06.md.
 
 import { exitSignal } from '../exec/index.js'
-import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { InputChanges, TaskNode, TaskOutcome } from '../graph/index.js'
 import { isGroupTask } from '../graph/index.js'
 import { maskedCommand, secretMask } from '../util/index.js'
 import type { Logger } from './logger.js'
@@ -250,6 +250,12 @@ export interface OutcomeView {
   blockedBy?: string
   /** How long an `admit` policy held the task with a worker free (see `TaskOutcome`). */
   admissionHeldMs?: number
+  /** How long the task waited ready for a worker (see `TaskOutcome`). */
+  queuedMs?: number
+  /** How many files a cacheable task's key read when it ran (see `TaskOutcome`). */
+  inputFiles?: number
+  /** What a missed task's key changed since its last saved entry (see `TaskOutcome`). */
+  inputChanges?: InputChanges
   restored?: boolean
   sandboxViolations?: number
   sandboxViolationLines?: string[]
@@ -369,6 +375,9 @@ export function projectOutcome(outcome: TaskOutcome): OutcomeView {
   if (outcome.cpuMs !== undefined) view.cpuMs = outcome.cpuMs
   if (outcome.peakRssBytes !== undefined) view.peakRssBytes = outcome.peakRssBytes
   if (outcome.admissionHeldMs !== undefined) view.admissionHeldMs = outcome.admissionHeldMs
+  if (outcome.queuedMs !== undefined) view.queuedMs = outcome.queuedMs
+  if (outcome.inputFiles !== undefined) view.inputFiles = outcome.inputFiles
+  if (outcome.inputChanges !== undefined) view.inputChanges = outcome.inputChanges
   if (outcome.timedOut === true) view.timedOut = true
   if (outcome.notReady !== undefined) view.notReady = outcome.notReady
   if (outcome.blockedBy !== undefined) view.blockedBy = outcome.blockedBy

package/src/orchestrator/execute-task.ts

@@ -68,6 +68,7 @@ import {
 import { markUnsaved, saveMiss, type OutputDirSnapshot } from './miss-save.js'
 import type { FingerprintWatch } from './fingerprint-watch.js'
 import { restoreHit } from './hit-restore.js'
+import type { MissExplainer } from './miss-reason.js'
 import { shellVerdict } from './shell-verdict.js'
 // The hit path's entry stays importable from here (tests).
 export { restoreHit, type RestoreHitArgs } from './hit-restore.js'
@@ -147,6 +148,8 @@ export interface ExecuteArgs {
   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
+  /** Name what a missed key changed (`createMissExplainer`); absent when nobody listens. */
+  explainMiss?: MissExplainer
   /**
    * Run-level retry default (`--retry <n>` / `RunOptions.retries`).
    * Explicit `exec.retries` wins, including an explicit 0. Threaded as
@@ -819,6 +822,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       if (c.kind === 'env' && named.includes(c.name) && !secretNamed(c.name))
         c.hash = MASKED + c.hash
   const inputs: TaskInputs | undefined = described?.inputs
+  const inputChanges = described !== undefined ? args.explainMiss?.(node.id, captured) : undefined
   // A plugin may keep the request past the run (the cache closed): it gets
   // the upstream outputs read now. Only the local floor leaves them unread.
   if (inputs !== undefined && !isLocalExecutor(args.executor)) void inputs.upstream
@@ -1361,6 +1365,10 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     hash,
     ...(attempt > 1 ? { attempts: attempt } : {}),
     ...(failedAttempts.length > 0 ? { failedAttempts } : {}),
+    ...(described !== undefined
+      ? { inputFiles: captured.reduce((n, c) => (c.kind === 'file' ? n + 1 : n), 0) }
+      : {}),
+    ...(inputChanges !== undefined ? { inputChanges } : {}),
     ...(unkeyed ? { unkeyed: true as const } : {}),
     ...(result.timedOut === true && effectiveExitCode !== 0 ? { timedOut: true as const } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),

package/src/orchestrator/miss-reason.ts

@@ -0,0 +1,55 @@
+// Why a task missed the cache, for telemetry: its key's components against
+// the last entry this cache saved for the same task. The `vx why` join
+// (`diffKeyComponents`), asked at run time instead of after it.
+//
+// Paid only when a telemetry sink exists, and only on a miss: one scan of
+// `entries` for the newest entry per task, the first time a miss asks, then
+// one primary-key read of that entry's `entry_inputs` per miss.
+
+import type { Database } from 'bun:sqlite'
+import type { InputChanges } from '../graph/index.js'
+import { diffKeyComponents } from './metrics.js'
+import type { TaskInputComponent } from './task-hash.js'
+
+/** How many changed components a miss names; `count` says how many there were. */
+const NAMED = 10
+
+export type MissExplainer = (
+  taskId: string,
+  components: readonly TaskInputComponent[],
+) => InputChanges | undefined
+
+export function createMissExplainer(db: Database): MissExplainer {
+  let newest: Map<string, string> | undefined
+  return (taskId, components) => {
+    try {
+      // Each task asks before its own command runs, so its own new entry is
+      // never the one it is compared with.
+      newest ??= new Map(
+        (
+          db
+            // A bare column beside MAX() comes from the row that has it.
+            .query(
+              'SELECT project, task, hash, MAX(created_at) FROM entries GROUP BY project, task',
+            )
+            .all() as { project: string; task: string; hash: string }[]
+        ).map((r) => [`${r.project}#${r.task}`, r.hash]),
+      )
+      const prev = newest.get(taskId)
+      if (prev === undefined) return undefined
+      const before = db
+        .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
+        .all(prev) as TaskInputComponent[]
+      // Pruned, or saved before fingerprints were kept: nothing to compare.
+      if (before.length === 0) return undefined
+      const { entries } = diffKeyComponents(before, components)
+      return {
+        count: entries.length,
+        first: entries.slice(0, NAMED).map(({ kind, name, change }) => ({ kind, name, change })),
+      }
+    } catch {
+      // History is observability: an unreadable one explains nothing.
+      return undefined
+    }
+  }
+}

package/src/orchestrator/run-context.ts

@@ -29,6 +29,16 @@ export interface CiContext {
   /** Which CI matched: 'github' | 'gitlab' | 'buildkite' | 'circleci'
    *  | 'generic' (bare `CI`), or null when no CI env is present. */
   provider: string | null
+  /** The provider's page for this run (a GitHub Actions run, a GitLab pipeline). */
+  runUrl?: string
+  /** The pull or merge request number this run builds. */
+  change?: string
+  /** The workflow or pipeline name. */
+  pipeline?: string
+  /** The job (or step) within it. */
+  job?: string
+  /** 1 on a first run, 2 on its first re-run. */
+  attempt?: number
 }
 
 export interface HostContext {
@@ -307,11 +317,71 @@ function isTruthy(v: string | undefined): boolean {
  */
 export function detectCi(env: NodeJS.ProcessEnv | Record<string, string | undefined>): CiContext {
   for (const [varName, provider] of CI_PROVIDERS) {
-    if (isTruthy(env[varName])) return { ci: true, provider }
+    if (isTruthy(env[varName])) return { ci: true, provider, ...ciLinks(provider, env) }
   }
   return { ci: false, provider: null }
 }
 
+type CiLinks = Pick<CiContext, 'runUrl' | 'change' | 'pipeline' | 'job' | 'attempt'>
+
+/** Where a dashboard links back to: each provider's own documented variables. */
+function ciLinks(provider: string, env: Record<string, string | undefined>): CiLinks {
+  const v = (k: string): string | undefined => (env[k] === '' ? undefined : env[k])
+  const n = (raw: string | undefined, plus = 0): number | undefined => {
+    const x = raw === undefined ? NaN : Number(raw)
+    return Number.isInteger(x) && x >= 0 ? x + plus : undefined
+  }
+  let links: Record<string, string | number | undefined>
+  switch (provider) {
+    case 'github': {
+      const server = v('GITHUB_SERVER_URL') ?? 'https://github.com'
+      const repo = v('GITHUB_REPOSITORY')
+      const id = v('GITHUB_RUN_ID')
+      links = {
+        runUrl: repo && id ? `${server}/${repo}/actions/runs/${id}` : undefined,
+        // `refs/pull/<n>/merge` on a pull_request event.
+        change: /^refs\/pull\/(\d+)\//.exec(v('GITHUB_REF') ?? '')?.[1],
+        pipeline: v('GITHUB_WORKFLOW'),
+        job: v('GITHUB_JOB'),
+        attempt: n(v('GITHUB_RUN_ATTEMPT')),
+      }
+      break
+    }
+    case 'gitlab':
+      links = {
+        runUrl: v('CI_PIPELINE_URL'),
+        change: v('CI_MERGE_REQUEST_IID'),
+        pipeline: v('CI_PIPELINE_NAME'),
+        job: v('CI_JOB_NAME'),
+      }
+      break
+    case 'buildkite': {
+      const pr = v('BUILDKITE_PULL_REQUEST')
+      links = {
+        runUrl: v('BUILDKITE_BUILD_URL'),
+        // `false` when the build is not for one.
+        change: pr !== undefined && /^\d+$/.test(pr) ? pr : undefined,
+        pipeline: v('BUILDKITE_PIPELINE_SLUG'),
+        job: v('BUILDKITE_LABEL'),
+        // Counts re-runs from 0.
+        attempt: n(v('BUILDKITE_RETRY_COUNT'), 1),
+      }
+      break
+    }
+    case 'circleci':
+      links = {
+        runUrl: v('CIRCLE_BUILD_URL'),
+        // The PR's URL, ending in its number.
+        change: /\/(\d+)$/.exec(v('CIRCLE_PULL_REQUEST') ?? '')?.[1] ?? v('CIRCLE_PR_NUMBER'),
+        job: v('CIRCLE_JOB'),
+      }
+      break
+    default:
+      return {}
+  }
+  return Object.fromEntries(Object.entries(links).filter(([, x]) => x !== undefined)) as CiLinks
+}
+
 /** Host name (null on failure) + platform + arch. */
 export function captureHostContext(): HostContext {
   let host: string | null = null

package/src/orchestrator/run.ts

@@ -92,6 +92,7 @@ import { writeRunProfile, writeRunSummary } from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
 import { formatRunSummary } from './summary.js'
 import { detectFlaky, type FlakyCandidate, type FlakyFinding } from './failure-mode.js'
+import { createMissExplainer } from './miss-reason.js'
 import type { RunOptions, RunSummary } from './options.js'
 
 // Per run, never shared: a `vx watch` process runs many, and a shared map
@@ -747,6 +748,11 @@ async function runOnBus(
         dirty: gitContext.dirty,
         ci: ciContext.ci,
         ciProvider: ciContext.provider,
+        ...(ciContext.runUrl !== undefined ? { ciRunUrl: ciContext.runUrl } : {}),
+        ...(ciContext.change !== undefined ? { ciChange: ciContext.change } : {}),
+        ...(ciContext.pipeline !== undefined ? { ciPipeline: ciContext.pipeline } : {}),
+        ...(ciContext.job !== undefined ? { ciJob: ciContext.job } : {}),
+        ...(ciContext.attempt !== undefined ? { ciAttempt: ciContext.attempt } : {}),
         host: hostContext.host,
         os: hostContext.os,
         arch: hostContext.arch,
@@ -916,6 +922,10 @@ async function runOnBus(
     const dependedOn = new Set<string>()
     for (const n of nodes.values()) for (const d of n.deps) dependedOn.add(d)
 
+    // Why a task missed, for a sink: a read of the history per miss, so only
+    // when a sink exists.
+    const explainMiss =
+      telemetry === undefined ? undefined : createMissExplainer(prepared.localCache.dbHandle())
     const buildExecuteArgs = (node: TaskNode, upstream: TaskOutcome[], reuseProbe = true) => {
       const probe = reuseProbe ? shortCircuit.preProbed.get(node.id) : undefined
       const upfrontKey = shortCircuit.uncachedKeys.get(node.id)
@@ -947,6 +957,7 @@ async function runOnBus(
         persistentRegistry,
         liveChildren,
         ...(telemetry?.track !== undefined ? { track: telemetry.track } : {}),
+        ...(explainMiss !== undefined ? { explainMiss } : {}),
         gitFilesCache,
         hashCache,
         ...(probe !== undefined ? { preProbed: probe } : {}),

package/src/orchestrator/telemetry.ts

@@ -17,7 +17,13 @@
 // core calls INTO; those are the behavior capabilities, kept separate.
 
 import { sampleTrees } from '../exec/index.js'
-import { isGroupTask, type TaskNode, type TaskOutcome, type TaskStatus } from '../graph/index.js'
+import {
+  isGroupTask,
+  type InputChanges,
+  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'
 
@@ -143,6 +149,16 @@ export interface RunContextRecord {
   dirty: boolean | null
   ci: boolean
   ciProvider: string | null
+  /** The CI provider's page for this run. */
+  ciRunUrl?: string
+  /** The pull or merge request number the run builds. */
+  ciChange?: string
+  /** The CI workflow or pipeline name. */
+  ciPipeline?: string
+  /** The CI job (or step) within it. */
+  ciJob?: string
+  /** 1 on a first run, 2 on its first re-run. */
+  ciAttempt?: number
   host: string | null
   os: string
   arch: string
@@ -207,6 +223,15 @@ export interface TaskTelemetry {
   storedPeakRssBytes?: number
   /** How long an `admit` policy held the task once it was ready. Additive. */
   admissionHeldMs?: number
+  /** How long the task waited ready for a worker, any admission hold included. Additive. */
+  queuedMs?: number
+  /** On a cacheable task that ran: how many files its key read. Additive. */
+  inputFiles?: number
+  /**
+   * On a cacheable task that ran, when the cache holds an earlier entry for
+   * it: what its key changed since, the first ten named. Additive.
+   */
+  inputChanges?: InputChanges
   /**
    * On a cache hit: whether outputs were written this run (`true`) or the
    * disk already matched the entry and nothing was restored (`false`, an
@@ -741,6 +766,9 @@ export function taskTelemetryOf(o: TaskOutcome): TaskTelemetry {
   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 (o.queuedMs !== undefined) t.queuedMs = o.queuedMs
+  if (o.inputFiles !== undefined) t.inputFiles = o.inputFiles
+  if (o.inputChanges !== undefined) t.inputChanges = o.inputChanges
   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/workspace/workspace.ts

@@ -74,7 +74,9 @@ const decoder = new TextDecoder()
  * `^task` edges vanish, upstream hashes drop out of the cache key (stale
  * hits), and a second cache dir appears under the member. Claiming is decided
  * with the same globs `loadWorkspace` applies, so "the root that claims me"
- * and "the root that lists me as a project" cannot diverge.
+ * and "the root that lists me as a project" cannot diverge. An outer root
+ * that lists both the claimer and the claimed member outranks the claimer:
+ * from the claimer's own directory the walk reaches the outer root too.
  *
  * When no candidate claims `start` — a standalone package, or a subdirectory
  * of a single-project repo — the nearest candidate wins (the root itself IS
@@ -92,6 +94,9 @@ export async function findWorkspaceRoot(
   // The nearest manifest with workspace globs of its own, once passed: an
   // outer root claims the tree only by listing this directory itself.
   let inner: string | null = null
+  // The root that claims `start`, and the members it claimed it through.
+  let claimed: string | null = null
+  let members: string[] = []
   while (true) {
     let globs: string[] | null
     try {
@@ -105,12 +110,23 @@ export async function findWorkspaceRoot(
     }
     if (globs !== null) {
       nearest ??= dir
-      if (claimsMember(dir, inner === null ? below : [inner], globs)) return dir
+      if (claimed !== null) {
+        // An outer root that lists both the claimer and the member owns
+        // them: `packages/**` holding `packages/inner` (with `workspaces:
+        // ['sub']`) and `packages/inner/sub` resolved `sub` to `inner` and
+        // `inner` to the outer root, two roots and two keys for one tree.
+        if (claimsMember(dir, [claimed], globs) && claimsMember(dir, members, globs)) claimed = dir
+      } else if (claimsMember(dir, inner === null ? below : [inner], globs)) {
+        claimed = dir
+        members = inner === null ? [...below] : [inner]
+      }
       // pnpm takes the nearest `pnpm-workspace.yaml` as the root, listed or
       // not. Walking past it, `apps/inner` resolved to the outer workspace
       // while `apps/inner/pkgs/x` resolved to the inner one: two roots and
       // two caches for one tree (item 990). Already read: `reads` holds it.
-      if ((await readOnce(reads, path.join(dir, 'pnpm-workspace.yaml'))) !== null) return dir
+      if ((await readOnce(reads, path.join(dir, 'pnpm-workspace.yaml'))) !== null) {
+        return claimed ?? dir
+      }
     }
     const parent = path.dirname(dir)
     if (parent === dir) break
@@ -126,6 +142,7 @@ export async function findWorkspaceRoot(
     if (inner === null && globs !== null && globs.length > 0) inner = dir
     dir = parent
   }
+  if (claimed !== null) return claimed
   if (nearest !== null) return nearest
   throw new UserError(
     `Could not find a workspace root in any parent of ${start} ` +