@vzn/vx 0.0.530 → 0.0.532

package/package.json

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

package/src/cache/cache.ts

@@ -339,6 +339,7 @@ function entryOf(row: EntryRow, fileRows: OutputFileRow[]): CacheEntry {
     command: row.command,
     exitCode: row.exit_code,
     durationMs: row.duration_ms,
+    sizeBytes: row.size_bytes,
     ...(row.cpu_ms !== null ? { cpuMs: row.cpu_ms } : {}),
     ...(row.peak_rss_bytes !== null ? { peakRssBytes: row.peak_rss_bytes } : {}),
     outputFiles: fileRows.map((r) => r.path),
@@ -487,9 +488,24 @@ function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
+/** What a run's background uploads moved: totals over the ones that landed. */
+export interface UploadTally {
+  count: number
+  bytes: number
+  /** Summed per-upload time; uploads overlap, so this exceeds the wall. */
+  ms: number
+  failed: number
+}
+
 export class Cache implements CacheLayer {
   /** This IS the local layer — there is nothing slower behind it. */
   readonly hasRemote = false
+  /**
+   * The run's uploads to a remote behind this cache, tallied by the
+   * `LayeredCache` over it (a plugin's, constructed over `ctx.localCache`)
+   * so the run can report them without a method on the layer seam.
+   */
+  readonly uploads: UploadTally = { count: 0, bytes: 0, ms: 0, failed: 0 }
 
   private readonly db: Database
   private readonly insertEntry: ReturnType<Database['prepare']>
@@ -1457,9 +1473,17 @@ export class Cache implements CacheLayer {
       // leaves it or loops (item 748).
       const code = (err as NodeJS.ErrnoException).code
       if (code === 'EISDIR' || code === 'ENOTDIR' || code === 'EEXIST' || code === 'ENOTEMPTY') {
+        // Bun's message already opens with the code: `EEXIST: EEXIST: …` read
+        // as a stutter. EEXIST and ENOTDIR are a FILE in a directory's
+        // place; the told-backwards sentence named only the reverse (X-7).
+        const msg = (err as Error).message
+        const what =
+          code === 'EISDIR' || code === 'ENOTEMPTY'
+            ? 'a directory stands where the entry holds a file'
+            : 'a file stands where the entry needs a directory'
         throw new UserError(
-          `restore of ${hash} into ${projectDir} was blocked by what is on disk (${code}: ${(err as Error).message}). ` +
-            `The clean before a restore removes the files the output globs select, not a directory standing where the entry holds a file, nor a path the globs do not cover — remove it and re-run.`,
+          `restore of ${hash} into ${projectDir} was blocked by what is on disk (${msg.startsWith(code) ? msg : `${code}: ${msg}`}): ${what}. ` +
+            `The clean before a restore removes the files the output globs select and the directories that empties, not this — remove it and re-run.`,
         )
       }
       // A legal name under a destination deep enough that the two together

package/src/cache/layer.ts

@@ -159,6 +159,10 @@ export interface CacheEntry {
    * them work vs. a stale-local replay.
    */
   source?: 'local' | 'remote'
+  /** The artifact's compressed size, when the index knows it. */
+  sizeBytes?: number
+  /** On a remote hit this run pulled: how long the download and its ingest took. */
+  fetchMs?: number
 }
 
 export interface RunRecord {

package/src/cache/layered-cache.ts

@@ -260,8 +260,9 @@ export class LayeredCache implements CacheLayer {
    * remote cache — so we flip `source` to `'remote'` and the
    * orchestrator reports `cache-hit-remote`. Without this, a prefetch
    * followed by a `get` would mislabel a genuine remote hit as local.
+   * Each maps to how long its download and ingest took.
    */
-  private readonly remoteSourced = new Set<string>()
+  private readonly remoteSourced = new Map<string, number>()
 
   /**
    * Background write-through uploads. `save()` returns after the local
@@ -364,7 +365,7 @@ export class LayeredCache implements CacheLayer {
       // A prefetch this run may have materialized this entry FROM
       // remote; the local row exists now, but the work was saved by
       // the remote cache, so the provenance stays 'remote'.
-      return this.remoteSourced.has(hash) ? { ...localHit, source: 'remote' } : localHit
+      return this.asRemote(hash, localHit)
     }
 
     // Remote reads disabled (e.g. `--cache=remote:`): a local miss is a
@@ -395,7 +396,12 @@ export class LayeredCache implements CacheLayer {
     // above and that skip's `local.has`, stamping 'remote' here reported a
     // purely-local hit as `cache-hit-remote` and inflated the remote
     // hit-rate. Whatever provenance the entry has is the truth.
-    return this.remoteSourced.has(hash) ? { ...materialized, source: 'remote' } : materialized
+    return this.asRemote(hash, materialized)
+  }
+
+  private asRemote(hash: string, entry: CacheEntry): CacheEntry {
+    const fetchMs = this.remoteSourced.get(hash)
+    return fetchMs === undefined ? entry : { ...entry, source: 'remote', fetchMs }
   }
 
   // Existence probe: local first, then a remote HEAD — no body
@@ -439,6 +445,7 @@ export class LayeredCache implements CacheLayer {
     // or remote if a concurrent prefetch set it).
     if ((await this.local.has(hash)) === 'local') return true
 
+    const fetchStart = performance.now()
     let remoteResult: unknown
     try {
       remoteResult = await this.wire.get(hash)
@@ -490,7 +497,7 @@ export class LayeredCache implements CacheLayer {
       this.reportRemoteError('download', hash, err)
       return false
     }
-    this.remoteSourced.add(hash)
+    this.remoteSourced.set(hash, Math.round(performance.now() - fetchStart))
     return true
   }
 
@@ -543,11 +550,17 @@ export class LayeredCache implements CacheLayer {
       }
     }
     this.enqueueUpload(async () => {
+      const tally = this.local.uploads
+      const start = performance.now()
       try {
         const body =
           packed !== undefined ? new Blob([packed]) : Bun.file(this.local.outputsPath(hash))
         await this.wire.put(hash, body, { durationMs })
+        tally.count++
+        tally.bytes += body.size
+        tally.ms += Math.round(performance.now() - start)
       } catch (err) {
+        tally.failed++
         this.reportRemoteError('upload', hash, err)
       }
     })

package/src/graph/scheduler.ts

@@ -86,6 +86,15 @@ export interface TaskOutcome {
   queuedMs?: number
   /** On a cacheable task that ran: how many files its key read. */
   inputFiles?: number
+  /**
+   * The artifact's compressed size: on a hit, the entry's; on a miss, the one
+   * its save wrote (measured only when a telemetry sink listens).
+   */
+  artifactBytes?: number
+  /** On a remote hit this run pulled: the download and its ingest. */
+  fetchMs?: number
+  /** On a miss that saved, with a sink listening: the save's own time. */
+  saveMs?: 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.
@@ -234,7 +243,7 @@ export interface ScheduleOptions {
    * execute request), so it waits for the save to land, while the freed
    * slot admits other work at once. Undefined: nothing owed.
    */
-  settledOf?: (outcome: TaskOutcome) => Promise<void> | undefined
+  settledOf?: (outcome: TaskOutcome) => Promise<Partial<TaskOutcome> | void> | undefined
   /**
    * Optional priority override: callers pass their own per-node weight
    * (e.g. `computePredictedPriorities` from the orchestrator's history
@@ -826,11 +835,12 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               return
             }
             tick()
-            const done = (): void => {
-              finishOne(id, outcome)
+            // What the save cost rides the outcome it settles.
+            const done = (owed?: Partial<TaskOutcome> | void): void => {
+              finishOne(id, owed ? { ...outcome, ...owed } : outcome)
               tick()
             }
-            void settled.then(done, done)
+            void settled.then(done, () => done())
           },
           (err: unknown) => {
             if (err instanceof RestoreDemoted) {

package/src/orchestrator/events.ts

@@ -256,6 +256,12 @@ export interface OutcomeView {
   inputFiles?: number
   /** What a missed task's key changed since its last saved entry (see `TaskOutcome`). */
   inputChanges?: InputChanges
+  /** The artifact's compressed size, a hit's or a measured save's (see `TaskOutcome`). */
+  artifactBytes?: number
+  /** A remote hit's download and ingest (see `TaskOutcome`). */
+  fetchMs?: number
+  /** A measured save's own time (see `TaskOutcome`). */
+  saveMs?: number
   restored?: boolean
   sandboxViolations?: number
   sandboxViolationLines?: string[]
@@ -378,6 +384,9 @@ export function projectOutcome(outcome: TaskOutcome): OutcomeView {
   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.artifactBytes !== undefined) view.artifactBytes = outcome.artifactBytes
+  if (outcome.fetchMs !== undefined) view.fetchMs = outcome.fetchMs
+  if (outcome.saveMs !== undefined) view.saveMs = outcome.saveMs
   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

@@ -65,7 +65,7 @@ import {
   type WithheldLink,
   withheldLinkLine,
 } from './sandbox-request.js'
-import { markUnsaved, saveMiss, type OutputDirSnapshot } from './miss-save.js'
+import { markUnsaved, saveMiss, type OutputDirSnapshot, type SaveFacts } from './miss-save.js'
 import type { FingerprintWatch } from './fingerprint-watch.js'
 import { restoreHit } from './hit-restore.js'
 import type { MissExplainer } from './miss-reason.js'
@@ -211,7 +211,7 @@ export interface ExecuteArgs {
    * in-flight join (admission.ts): a duplicate of this task in another run
    * must not probe the cache before the entry is there.
    */
-  deferredSaves?: Map<string, Promise<void>>
+  deferredSaves?: Map<string, Promise<SaveFacts>>
   /**
    * `continueMode: 'always'` let this task run although an upstream —
    * directly or through a chain of successes — failed or aborted. It still
@@ -1261,6 +1261,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
       outputDirSnapshots: args.outputDirSnapshots,
       deferSave: args.deferSave,
+      // A sink listens: say what the save cost.
+      measure: args.explainMiss !== undefined,
     })
     args.deferredSaves?.set(node.id, landed)
   } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants !== true) {

package/src/orchestrator/hit-restore.ts

@@ -303,6 +303,8 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     storedDurationMs: hit.durationMs,
     ...(hit.cpuMs !== undefined ? { storedCpuMs: hit.cpuMs } : {}),
     ...(hit.peakRssBytes !== undefined ? { storedPeakRssBytes: hit.peakRssBytes } : {}),
+    ...(hit.sizeBytes !== undefined ? { artifactBytes: hit.sizeBytes } : {}),
+    ...(hit.fetchMs !== undefined ? { fetchMs: hit.fetchMs } : {}),
     hash,
     restored,
     wallclockStartNs: taskStartNs,

package/src/orchestrator/miss-save.ts

@@ -7,7 +7,7 @@
 // a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
 // code motion.
 
-import { lstatSync, realpathSync } from 'node:fs'
+import { lstatSync, realpathSync, statSync } from 'node:fs'
 import path from 'node:path'
 import {
   type CacheLayer,
@@ -91,10 +91,21 @@ export interface SaveMissArgs {
    * index go to the run's save lane (save-lane.ts).
    */
   deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+  /** Time the save and size its artifact, for a telemetry sink: one stat. */
+  measure?: boolean | undefined
 }
 
-/** `landed` settles when the entry is in the cache — at once without a lane. */
-export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void> }> {
+/** What a measured save cost, on the outcome once it lands. */
+export interface SaveFacts {
+  saveMs?: number
+  artifactBytes?: number
+}
+
+/**
+ * `landed` settles when the entry is in the cache — at once without a lane —
+ * with what it cost when `measure` asked.
+ */
+export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveFacts> }> {
   const { node, cache, log } = a
   const endResolve = span('miss: resolve outputs')
   const outputFiles =
@@ -145,7 +156,9 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void>
             : ''),
     )
   }
+  const facts: SaveFacts = {}
   const save = async (): Promise<void> => {
+    const saveStart = a.measure === true ? performance.now() : 0
     const endSave = span('miss: save')
     // Tier-3 input fingerprint: the digest rows captured by the pre-exec
     // describe above, persisted with the entry inside `cache.save`'s
@@ -171,6 +184,14 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void>
       },
     })
     endSave()
+    if (a.measure === true) {
+      facts.saveMs = Math.round(performance.now() - saveStart)
+      try {
+        facts.artifactBytes = statSync(cache.outputsPath(a.hash)).size
+      } catch {
+        // No local artifact (local writes off): no size to say.
+      }
+    }
     // The files the task just wrote are the entry's bytes: stamp them,
     // so the next hit can tell them from another entry's with the same
     // size and mtime (item 886).
@@ -198,9 +219,9 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void>
   // Off the slot when the run keeps a lane (the save lane bounds and
   // drains it); in the slot otherwise — an embedder without a lane gets
   // the entry before the outcome.
-  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
+  if (a.deferSave !== undefined) return { landed: a.deferSave(save).then(() => facts) }
   await save()
-  return { landed: Promise.resolve() }
+  return { landed: Promise.resolve(facts) }
 }
 
 /** What `markUnsaved` reads of a miss: where its declared outputs are. */

package/src/orchestrator/run.ts

@@ -42,7 +42,7 @@ import {
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { prepareSandbox } from './sandbox-request.js'
-import type { OutputDirSnapshot } from './miss-save.js'
+import type { OutputDirSnapshot, SaveFacts } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
 import { excludedTaint } from './excluded-keys.js'
 import { keyUpstream } from './upstream.js'
@@ -800,7 +800,7 @@ async function runOnBus(
     const saveLane = createSaveLane(2 * concurrency, (err) =>
       log.status(`[vx] cache save failed: ${err instanceof Error ? err.message : String(err)}`),
     )
-    const deferredSaves = new Map<string, Promise<void>>()
+    const deferredSaves = new Map<string, Promise<SaveFacts>>()
 
     // Focused flow: a requested GROUP has no output of its own, so
     // surface the same-project, non-group tasks it chains (one level)
@@ -1209,27 +1209,6 @@ async function runOnBus(
       log.status(`[vx] run history not recorded: ${message} — the verdict above stands`)
     }
     mark('record history')
-    // Hand the per-run summary to the telemetry sinks + drain them. Only
-    // when a sink is active (telemetry !== undefined) — otherwise this
-    // whole block is skipped and the run is byte-identical to before.
-    // emitSummary/flush are crash-isolated, so a faulty sink can't fail
-    // the run; flush is the sink's last chance to ship buffered records.
-    if (telemetry !== undefined && runContextRecord !== undefined) {
-      const summary = assembleRunSummary(runContextRecord, records.telemetryTasks, {
-        startedAt: endedAtMsAtStart,
-        endedAt: endedAtMs,
-        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()
-    }
-    // End-of-run plugin lifecycle: each plugin's teardown(). Crash-isolated
-    // + time-bounded inside teardownPlugins, so a faulty plugin can neither
-    // fail nor hang the run. Here on the normal path, after the drains
-    // below; every other exit takes it through `teardown` too.
     // 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
@@ -1252,6 +1231,30 @@ async function runOnBus(
     // drain of the lane stood here until item 634; deleting it changed
     // nothing the suite could see, because this gate is the rule.
     await cache.drainUploads?.()
+    // Hand the per-run summary to the telemetry sinks + drain them. Only
+    // when a sink is active (telemetry !== undefined) — otherwise this
+    // whole block is skipped and the run is byte-identical to before.
+    // emitSummary/flush are crash-isolated, so a faulty sink can't fail
+    // the run; flush is the sink's last chance to ship buffered records.
+    // After the drain, so the summary says what the uploads moved; a live
+    // sink's task records went out as each task ended.
+    if (telemetry !== undefined && runContextRecord !== undefined) {
+      const summary = assembleRunSummary(runContextRecord, records.telemetryTasks, {
+        startedAt: endedAtMsAtStart,
+        endedAt: endedAtMs,
+        totalDurationMs: Math.round(totalMs),
+        exitOk: ok,
+        abortedCount: list.filter((o) => o.status === 'aborted' && !isGroupTask(o.node)).length,
+        stages: stageTimes(),
+        uploads: prepared.localCache.uploads,
+      })
+      telemetry.emitSummary(summary)
+      await telemetry.flush()
+    }
+    // End-of-run plugin lifecycle: each plugin's teardown(). Crash-isolated
+    // + time-bounded inside teardownPlugins, so a faulty plugin can neither
+    // fail nor hang the run. Here on the normal path, after the drains
+    // above; every other exit takes it through `teardown` too.
     // The miss path's output-directory snapshots, taken now that the
     // directories are old enough for the snapshot's racy window (see
     // miss-save.ts). A few at a time: each is an lstat + readdir per

package/src/orchestrator/telemetry.ts

@@ -232,6 +232,12 @@ export interface TaskTelemetry {
    * it: what its key changed since, the first ten named. Additive.
    */
   inputChanges?: InputChanges
+  /** The artifact's compressed size: on a hit the entry's, on a miss the save's. Additive. */
+  artifactBytes?: number
+  /** On a remote hit this run pulled: the download and its ingest. Additive. */
+  fetchMs?: number
+  /** On a miss that saved: the save's own time (pack, write, index). Additive. */
+  saveMs?: 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
@@ -339,6 +345,12 @@ export interface RunSummaryRecord {
    * stages ahead of the run lock end before `startedAt`. Additive.
    */
   stages?: readonly RunStage[]
+  /**
+   * The run's uploads to a remote cache, once they settled: how many landed,
+   * their bytes, their summed time (they overlap), and how many failed.
+   * Absent when nothing was uploaded or tried. Additive.
+   */
+  uploads?: { count: number; bytes: number; ms: number; failed: number }
 }
 
 /** One stage of a run, a wall window in epoch ms. */
@@ -369,6 +381,7 @@ export function assembleRunSummary(
     exitOk: boolean
     abortedCount: number
     stages?: readonly RunStage[]
+    uploads?: { count: number; bytes: number; ms: number; failed: number }
   },
 ): RunSummaryRecord {
   let failedCount = 0
@@ -404,6 +417,9 @@ export function assembleRunSummary(
     exitOk: timing.exitOk,
     tasks,
     ...(timing.stages !== undefined && timing.stages.length > 0 ? { stages: timing.stages } : {}),
+    ...(timing.uploads !== undefined && timing.uploads.count + timing.uploads.failed > 0
+      ? { uploads: { ...timing.uploads } }
+      : {}),
   }
 }
 
@@ -769,6 +785,9 @@ export function taskTelemetryOf(o: TaskOutcome): TaskTelemetry {
   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 (o.artifactBytes !== undefined) t.artifactBytes = o.artifactBytes
+  if (o.fetchMs !== undefined) t.fetchMs = o.fetchMs
+  if (o.saveMs !== undefined) t.saveMs = o.saveMs
   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/project-loader.ts

@@ -294,7 +294,12 @@ export function configLoadError(err: unknown, configPath: string, kind: string):
   // below are Bun's own and nothing else answers to them, so this is
   // narrower than it looks: every other throw still passes through (2026-09-20).
   if (err === null || typeof err !== 'object') return null
-  const { name, message } = err as { name?: unknown; message?: unknown }
+  const { name, message, errors } = err as { name?: unknown; message?: unknown; errors?: unknown }
+  // Two syntax errors arrive as one `AggregateError` of `BuildMessage`s,
+  // which printed a stack and no position (X-6). The first is where to look.
+  if (name === 'AggregateError' && Array.isArray(errors) && errors.length > 0) {
+    return configLoadError(errors[0], configPath, kind)
+  }
   if (typeof message !== 'string') return null
   if (name === 'ResolveMessage') {
     const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message)?.[1]