@vzn/vx 0.0.640 → 0.0.641

package/src/orchestrator/run-report.ts

@@ -1,11 +1,14 @@
 // The report every plugin's teardown reads, and the run's own bytes kept
 // in a remote that takes its writes (owner 2026-10-15): a failed task's
 // log and the files its outputs left (`cache.upload.failures`), and the
-// log of a task that saved no entry. Each task's bytes leave when it ends,
-// off its path, like its entry's upload (owner 2026-10-16); the run only
-// waits for them where it waits for every upload.
+// log of a task that saved no entry, on every run (M, 2026-10-16: "Always
+// keep"). Each task's bytes leave when it ends, off its path, like its
+// entry's upload (owner 2026-10-16); the run only waits for them where it
+// waits for every upload, and the footer counts them as the task's remote
+// traffic.
 
 import {
+  type RemoteTraffic,
   packRunOutputs,
   resolveOutputs,
   resolveWorkspaceOutputs,
@@ -27,6 +30,8 @@ export interface RunKeeperArgs {
   readonly keep: KeepRunEntry
   /** Whether a failed task's log and outputs are kept (`cache.upload.failures`). */
   readonly failures: boolean
+  /** The footer's remote traffic: each kept task counts under its id. */
+  readonly traffic: RemoteTraffic
 }
 
 /** Whether a run on CI or off it keeps failures, by `cache.upload.failures` (default `'ci'`). */
@@ -81,8 +86,10 @@ export class RunKeeper {
       if (text.length > 0) {
         const name = runEntryName(runId, id, 'log')
         const bytes = new TextEncoder().encode(text)
-        this.enqueue(async () => {
-          if (await this.args.keep(name, bytes)) slot().log = name
+        this.enqueue(id, async () => {
+          if (!(await this.args.keep(name, bytes))) return false
+          slot().log = name
+          return true
         })
       }
     }
@@ -94,9 +101,11 @@ export class RunKeeper {
         this.args.nestedDirsByProject.get(o.node.projectName) ?? [],
       ).then((paths) => packRunOutputs(workspaceRoot, paths))
       const name = runEntryName(runId, id, 'outputs')
-      this.enqueue(async () => {
+      this.enqueue(id, async () => {
         const bytes = await packed
-        if (bytes !== null && (await this.args.keep(name, bytes))) slot().outputs = name
+        if (bytes === null || !(await this.args.keep(name, bytes))) return false
+        slot().outputs = name
+        return true
       })
     }
   }
@@ -117,16 +126,28 @@ export class RunKeeper {
     return this.kept.get(id)
   }
 
-  private enqueue(job: () => Promise<void>): void {
+  /** Queue `job`, which writes `id`'s bytes; a write that lands counts as `id`'s upload. */
+  private enqueue(id: string, job: () => Promise<boolean>): void {
     let done!: () => void
     const p = new Promise<void>((resolve) => (done = resolve))
     this.pending.add(p)
+    const { traffic } = this.args
+    let key = traffic.keys.get(id)
+    if (key === undefined)
+      traffic.keys.set(id, (key = { uploading: 0, landed: false, failures: [] }))
+    const counted = key
+    counted.uploading++
+    traffic.inFlight++
     this.queue.push(async () => {
       try {
-        if (!this.stopped) await job()
+        if (!this.stopped && (await job())) counted.landed = true
       } catch {
         // a record, never the run's verdict
       } finally {
+        counted.uploading--
+        traffic.inFlight--
+        if (counted.uploading === 0 && !counted.landed && counted.failures.length === 0)
+          traffic.keys.delete(id)
         this.pending.delete(p)
         done()
       }

package/src/orchestrator/run.ts

@@ -8,11 +8,11 @@ import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
   Cache,
-  type CacheLayer,
   type CachePolicy,
   cachesNothing,
   formatCachePolicy,
   stopRuntimeProbes,
+  sweepStaging,
 } from '../cache/index.js'
 import { VERSION } from '../version.js'
 import {
@@ -162,17 +162,14 @@ function effectiveCachePolicy(requested: CachePolicy, hasRemoteLayer: boolean):
 /**
  * The perf firewall for the local short-circuit. Always-on; the only
  * gates are correctness/no-op gates:
- *   - LOCAL-ONLY cache. Behind a remote layer, `cache.get` is a remote
- *     READ-THROUGH — the up-front classify is awaited before scheduling,
- *     so N remote GETs would land on the critical path before any task
- *     starts. Remote runs are owned by `startRemotePrefetch`, which
- *     overlaps the GETs with execution instead (fire-and-forget) and
- *     ingests hits into local for execute-task's lazy probe. The gate asks
- *     the layer (`hasRemote`), not `instanceof LayeredCache` — a
- *     third-party remote layer stalls on the classify just as hard.
  *   - the policy reads locally (a `--no-cache`/`--force`/`--cache-policy=local:`
  *     run reads nothing locally → nothing to restore → skip);
  *   - there is at least one task.
+ * A remote layer does not close it: the local cache sits in front of every
+ * remote (#3619), so the classify probes that local store alone and a local
+ * hit runs ahead of its dependencies as it does with no remote; the remote
+ * GETs stay on `startRemotePrefetch`'s fire-and-forget path (M's solid
+ * run, 2026-10-16: a local hit waited 18 s on a dependency it never read).
  * A flat graph has no ordering to bypass, but the classify pass is worth
  * paying for anyway: it probes every stable key through ONE batched
  * `getMany` instead of a `cache.get` per task inside the run, which
@@ -180,12 +177,7 @@ function effectiveCachePolicy(requested: CachePolicy, hasRemoteLayer: boolean):
  * (2026-09-03, interleaved arms). The per-task correctness gates (stable
  * key, no workspace-outputs in graph) live in `startLocalShortCircuit`.
  */
-export function shouldShortCircuit(
-  nodes: Map<string, TaskNode>,
-  policy: CachePolicy,
-  cache: CacheLayer,
-): boolean {
-  if (cache.hasRemote === true) return false
+export function shouldShortCircuit(nodes: Map<string, TaskNode>, policy: CachePolicy): boolean {
   if (!policy.localRead) return false
   return nodes.size > 0
 }
@@ -450,6 +442,8 @@ async function runOnBus(
   // carries it so analytics queries can group by invocation; plugins get it
   // in their teardown's `RunReport`.
   const runId = ulid()
+  // A killed run's restore staging (`.vx/tmp/<pid>-0`), once per run.
+  sweepStaging(prepared.workspaceRoot)
   const head = captureGitContext(prepared.workspaceRoot)
   const ciContext = detectCi(process.env)
   const keepRun =
@@ -470,6 +464,7 @@ async function runOnBus(
           nestedDirsByProject: prepared.nestedDirsByProject,
           keep: prepared.keepRunEntry,
           failures: keepRun.failures,
+          traffic: prepared.localCache.traffic,
         })
   try {
     disposePlugins = await installPlugins({
@@ -873,16 +868,22 @@ async function runOnBus(
     // An empty local cache answers every probe with a miss: each task
     // derives its key as it starts instead (~100 ms before a cold 1,090-
     // package run's first spawn), and every sandboxed task runs.
+    const remote = cache.hasRemote === true
     const coldLocal =
-      cache === prepared.localCache &&
-      shouldShortCircuit(nodes, policy, cache) &&
-      prepared.localCache.holdsNothing()
-    if (coldLocal) prewarm()
-    else if (shouldShortCircuit(nodes, policy, cache)) {
+      shouldShortCircuit(nodes, policy) && (remote || cache === prepared.localCache)
+        ? prepared.localCache.holdsNothing()
+        : false
+    // 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)) {
       shortCircuit = await step('vx:keys', () =>
         startLocalShortCircuit({
           nodes,
-          cache,
+          // Behind a remote, the local store alone: its hits are certain
+          // now, and a local miss may still be a remote hit.
+          cache: remote ? prepared.localCache : cache,
+          localOnly: remote,
           workspaceRoot,
           claimedFiles: fingerprintWatch.names,
           forwardArgs: options.forwardArgs,
@@ -893,7 +894,8 @@ async function runOnBus(
         }),
       )
       // A confirmed miss runs too.
-      if (sandboxed.some((n) => shortCircuit.preProbed.get(n.id)?.hit === null)) prewarm()
+      if (!remote && sandboxed.some((n) => shortCircuit.preProbed.get(n.id)?.hit === null))
+        prewarm()
     }
 
     // Whether this task runs behind a failure (`continueMode: 'always'`
@@ -1605,7 +1607,7 @@ async function planRestorable(
   const serves = [...nodes.values()].some(
     (n) => n.config.exec?.persistent !== undefined && !n.requested && n.surfaced !== true,
   )
-  if (!serves || !shouldShortCircuit(nodes, policy, prepared.cache)) return {}
+  if (!serves || !shouldShortCircuit(nodes, policy)) return {}
   const keptOut = restoreTierExclusions(nodes, prepared.workspaceRoot)
   const stable = await deriveStableKeys({
     nodes,

package/src/report/logger.ts

@@ -973,8 +973,11 @@ export function defaultLogger(
           const qi = slotQueue.findIndex((s) => s.id === node.id)
           if (qi >= 0) slotQueue.splice(qi, 1)
         }
-        const bucket = outcome.hash === undefined ? undefined : cacheBucketOf(outcome)
-        if (bucket !== undefined) buckets.set(outcome.hash!, bucket)
+        const bucket = cacheBucketOf(outcome)
+        if (bucket !== undefined) {
+          if (outcome.hash !== undefined) buckets.set(outcome.hash, bucket)
+          buckets.set(node.id, bucket)
+        }
         switch (outcome.status) {
           case 'success':
             succeeded++

package/src/report/summary.ts

@@ -110,7 +110,7 @@ export interface SummaryStats {
   savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
   emptyGroups?: readonly string[]
-  /** Each finished task's cache bucket by its key, so its remote traffic can move it. */
+  /** Each finished task's cache bucket by its key and its id (its run bytes), so its remote traffic can move it. */
   buckets?: ReadonlyMap<string, CacheBucket>
 }
 
@@ -536,12 +536,14 @@ export function formatRunSummary(
   )
 }
 
-/** Each finished task's cache bucket by its key. */
+/** Each finished task's cache bucket by its key and by its id. */
 function bucketsOf(outcomes: readonly TaskOutcome[]): Map<string, CacheBucket> {
   const out = new Map<string, CacheBucket>()
   for (const o of outcomes) {
-    const bucket = o.hash === undefined ? undefined : cacheBucketOf(o)
-    if (bucket !== undefined) out.set(o.hash!, bucket)
+    const bucket = cacheBucketOf(o)
+    if (bucket === undefined) continue
+    if (o.hash !== undefined) out.set(o.hash, bucket)
+    out.set(o.node.id, bucket)
   }
   return out
 }

package/src/util/index.ts

@@ -58,7 +58,10 @@ export {
   GLOB_WILDCARDS,
   normalizeBunGlob,
   normalizeGlob,
+  namesNodeModules,
+  OUTPUT_NEVER,
   outputMatcher,
+  restorableOutput,
   printable,
   relPosix,
   DOT_VX_GITATTRIBUTES,

package/src/util/paths.ts

@@ -12,11 +12,12 @@ export function toPosix(p: string): string {
 }
 
 /**
- * `.vx/.gitignore`: git ignores the machine-local `.vx/cache` and nothing
- * else in `.vx`, so the workspace config and the lock beside it are
- * committed. `vx init` and the cache write it when missing.
+ * `.vx/.gitignore`: git ignores the machine-local `.vx/cache`, `.vx/tmp`
+ * (where restores stage) and nothing else in `.vx`, so the workspace
+ * config and the lock beside it are committed. `vx init` and the cache
+ * write it when missing.
  */
-export const DOT_VX_GITIGNORE = '/cache\n'
+export const DOT_VX_GITIGNORE = '/cache\n/tmp\n'
 
 /** `.vx/.gitattributes`' text: GitHub collapses the machine lock in a diff. */
 export const DOT_VX_GITATTRIBUTES = 'projects.lock.json linguist-generated=true\n'
@@ -385,6 +386,39 @@ export function outputMatcher(globs: readonly string[]): (rel: string) => boolea
   return (rel) => pos(rel) && !neg(rel)
 }
 
+/**
+ * What no output glob reaches. An output is otherwise taken as written —
+ * `node_modules/**` IS an install task's output — but no task produces
+ * these, and a root project declaring `**` would otherwise wipe its
+ * repository and the cache it is restoring from (2026-09-16). `.vx` whole
+ * and each `vx.lock.json` are vx's own: as outputs, the clean deleted an
+ * uncommitted workspace config and a hit restored a lock or ignore file the
+ * key does not see over the current one.
+ */
+export const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
+
+/** Whether a positive glob in `globs` names a `node_modules` directory. */
+export function namesNodeModules(globs: readonly string[]): boolean {
+  return globs.some(
+    (g) => !g.startsWith('!') && normalizeGlob(g).split('/').includes('node_modules'),
+  )
+}
+
+/**
+ * Whether a restore may write `rel`: one of the outputs `globs` declare,
+ * never under `OUTPUT_NEVER`, and under `node_modules` only where a glob
+ * names it — what the save side could have packed (`resolveOutputs`). An
+ * artifact naming anything else was not written by this task's save, and
+ * none of it is restored (2026-10-16).
+ */
+export function restorableOutput(globs: readonly string[]): (rel: string) => boolean {
+  const isOutput = outputMatcher(globs)
+  const never = anyTaskGlob(
+    namesNodeModules(globs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**'],
+  )
+  return (rel) => isOutput(rel) && !never(rel)
+}
+
 /**
  * `pattern` with its first brace group expanded, recursively, while that
  * group holds a `/`; any other pattern as itself, since `Bun.Glob`

package/src/workspace/config-eval.ts

@@ -103,7 +103,7 @@ const nonJsonPaths = ${nonJsonPaths.toString()}
     throw new Error('process.exit(' + (code ?? '') + ') in a config: ' + ${JSON.stringify(CONFIG_EXIT)})
   }
 }
-// Bun's resolver reads \\ as a separator, so a config under a\\b is served
+// Bun's resolver reads \\ as a separator and ? as a query, so a config under a\\b or a?b is served
 // from the path as written (project-loader.ts's LITERAL_QUERY), read now.
 let literal = false
 const serveLiteral = () => {
@@ -172,7 +172,7 @@ self.onmessage = async (e) => {
     if (umaskIn !== null && globalThis.process.umask() !== umaskIn) globalThis.process.umask(umaskIn)
   }
   try {
-    const literalPath = path.includes('\\\\')
+    const literalPath = /[\\\\?]/.test(path)
     if (literalPath) serveLiteral()
     const ns = await import(literalPath ? path + '?vx-literal' : path)
     // Awaited as the in-process load's async return flattens it: a Promise

package/src/workspace/project-loader.ts

@@ -75,8 +75,9 @@ let serving = false
 const HELD_QUERY = /\?vx-(?:held|literal)=([0-9a-f]+)$/
 
 // Bun's resolver reads `\` as a separator, even in a file: URL, so a
-// config under `a\b` was looked for under `a/b`. Resolving it here keeps
-// the path as written; only the served load can take it.
+// config under `a\b` was looked for under `a/b`, and `?` as a query, so
+// one under `a?b` was looked for under `a`. Resolving it here keeps the
+// path as written; only the served load can take it.
 const LITERAL_QUERY = /\?vx-literal=[0-9a-f]+$/
 
 function serveHeldSources(): void {
@@ -148,14 +149,14 @@ async function loadDefaultExport(
   // URL yet, and a repeat load (the one that could replay an evaluation
   // made under earlier env values) re-evaluates in a worker instead
   // (`loadedConfigs`, item 678).
-  const literal = configPath.includes('\\')
+  const literal = /[\\?]/.test(configPath)
   const source =
     kind === 'Project' || literal
       ? servableSource(bytes, /\.[cm]?ts$/.test(configPath) ? 'ts' : 'js')
       : null
   if (literal && source === null) {
     throw new UserError(
-      `${kind} config ${configPath} sits under a path that holds a backslash, which Bun loads only as an ES module in UTF-8`,
+      `${kind} config ${configPath} sits under a path that holds ${configPath.includes('\\') ? 'a backslash' : 'a question mark'}, which Bun loads only as an ES module in UTF-8`,
     )
   }
   const hash = xxh3hex(bytes)