@vzn/vx 0.0.638 → 0.0.640

package/docs/security.md

@@ -217,7 +217,7 @@ executor's error, telemetry,
 `vx show` (L-26). Values in the run history are digests under a per-store
 salt, and what follows `--` on the command line reaches telemetry as a
 count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
-task's `exec.env.define` values and the `cache.inputs.env` values its
+task's `exec.env.define` values and the `inputs.env` values its
 local child gets, never `passThrough`; those values sit unmasked in the
 action's Command, which the remote stores in its CAS, as Bazel's
 `--action_env` does, so a secret a remote task needs is trusted to that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.638",
+  "version": "0.0.640",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.638",
-    "@vzn/vx-linux-arm64": "0.0.638",
-    "@vzn/vx-darwin-x64": "0.0.638",
-    "@vzn/vx-darwin-arm64": "0.0.638"
+    "@vzn/vx-linux-x64": "0.0.640",
+    "@vzn/vx-linux-arm64": "0.0.640",
+    "@vzn/vx-darwin-x64": "0.0.640",
+    "@vzn/vx-darwin-arm64": "0.0.640"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/last.json

@@ -107,8 +107,7 @@
         "host",
         "os",
         "arch",
-        "vxVersion",
-        "tags"
+        "vxVersion"
       ],
       "properties": {
         "runId": { "type": "string" },
@@ -146,8 +145,7 @@
         "host": { "type": ["string", "null"] },
         "os": { "type": ["string", "null"] },
         "arch": { "type": ["string", "null"] },
-        "vxVersion": { "type": "string" },
-        "tags": { "type": "object", "additionalProperties": { "type": "string" } }
+        "vxVersion": { "type": "string" }
       }
     },
     "task": {
@@ -174,6 +172,7 @@
         "timedOut",
         "sandboxViolations",
         "notReady",
+        "remoteError",
         "forwarded"
       ],
       "properties": {
@@ -209,6 +208,10 @@
         "timedOut": { "type": ["boolean", "null"] },
         "sandboxViolations": { "type": ["integer", "null"] },
         "notReady": { "enum": ["timeout", "exited", "spawn", null] },
+        "remoteError": {
+          "type": ["string", "null"],
+          "description": "each failed remote read or write of the key, `; `-joined"
+        },
         "forwarded": { "type": "boolean" },
         "output": {
           "type": "string",

package/schemas/show.json

@@ -90,24 +90,24 @@
             }
           }
         },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "files": { "$ref": "#/$defs/stringList" },
+            "workspaceFiles": { "$ref": "#/$defs/stringList" },
+            "env": { "$ref": "#/$defs/stringList" },
+            "tasks": { "$ref": "#/$defs/stringList" },
+            "runtime": { "$ref": "#/$defs/stringList" },
+            "workspaceRuntime": { "$ref": "#/$defs/stringList" }
+          }
+        },
         "cache": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["inputs", "outputs"],
+          "required": ["outputs"],
           "properties": {
-            "inputs": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["files"],
-              "properties": {
-                "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" },
-                "env": { "$ref": "#/$defs/stringList" },
-                "tasks": { "$ref": "#/$defs/stringList" },
-                "runtime": { "$ref": "#/$defs/stringList" },
-                "workspaceRuntime": { "$ref": "#/$defs/stringList" }
-              }
-            },
             "outputs": {
               "type": "object",
               "additionalProperties": false,

package/skills/vx/SKILL.md

@@ -15,13 +15,13 @@ dependencies.
 vx run build --all                  # a task in every project that declares it
 vx run test --affected=origin/main  # only what the diff since origin/main reaches
 vx run app#build                    # one project's task (and what it depends on)
-vx run build --all --format json    # the result as JSON on stdout; logs go to stderr
+vx last --format json               # the last run's result as JSON
 ```
 
 The exit code is the verdict: `0` every task passed or hit the cache, `1` a
-task failed or was skipped, or the command was refused. `--format json`
-prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
-A refusal under `--format json` is one line on stdout,
+task failed or was skipped, or the command was refused. `vx last --format
+json` prints the run as JSON afterwards, a row per task. A refusal under
+`--format json` (or `--dry=json`) is one line on stdout,
 `{"ok":false,"error":{"code","message","docs"}}`: branch on `code`;
 `docs` (or `vx docs <code>` offline) says what to do.
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
@@ -90,9 +90,10 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 - Never delete or edit the cache by hand; vx repairs it itself.
 - A sandboxed task that fails on a denied path: grant that one path in
   `exec.sandbox.allow`. Never remove `sandbox` or widen it further.
-- A cached task declares its inputs (`cache.inputs.files`); if a change
-  does not re-run a task, the file is not one of its inputs. Fix the
-  config, do not force.
+- A task declares its inputs (`inputs.files`), cached or not; if a
+  change does not re-run a task, the file is not one of its inputs. Fix
+  the config, do not force. A task with no `inputs` has no key, so every
+  cached task behind it misses: give it `inputs`.
 - Every JSON shape is a JSON Schema in `node_modules/@vzn/vx/schemas/`.
 - Offline reference: `vx docs <words> --format json` searches the CLI, config
   and cache pages that ship with vx; the sections holding every word print
@@ -108,3 +109,5 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 `npx skills add vznjs/vx` installs this skill. To match the vx a workspace
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.
+`vx upgrade` inside a workspace moves the project's `@vzn/vx` and the
+global vx that ran it to the same version.

package/src/cache/cache.ts

@@ -96,6 +96,7 @@ import {
   type PruneResult,
   type RunRecord,
   type SaveArgs,
+  type TaskInputComponent,
   type TaskInputRow,
   WORKSPACE_OUTPUT_PREFIX,
 } from './layer.js'
@@ -111,6 +112,7 @@ import { FileHashStore } from './file-hashes.js'
 import { OutputIndex } from './output-index.js'
 import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
+import { behindLink } from './linked-inputs.js'
 
 /**
  * An artifact or temp file without an `entries` row is never reaped
@@ -309,17 +311,19 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //   v38: blob_sizes moved to the store, and the store's task_outcomes
 //        holds the flaky record, so worktrees share both. The cache KEY is
 //        unchanged.
-export const SCHEMA_VERSION = 'v38'
+//   v39: invocations drops `tags` (`--tag` is gone). The cache KEY is
+//        unchanged.
+//   v40: runs.remote_error — each remote read or write of a task's key that
+//        failed, for `vx last`. The cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v40'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
  * `[kind, name, hash]` triples in (kind, name) code-unit order, the first
  * of a repeated (kind, name) kept, as the per-component primary key did.
  */
-function encodeEntryInputs(
-  components: readonly Pick<TaskInputRow, 'kind' | 'name' | 'hash'>[],
-): string {
-  const byId = new Map<string, Pick<TaskInputRow, 'kind' | 'name' | 'hash'>>()
+function encodeEntryInputs(components: readonly TaskInputComponent[]): string {
+  const byId = new Map<string, TaskInputComponent>()
   for (const c of components) {
     const id = `${c.kind}\0${c.name}`
     if (!byId.has(id)) byId.set(id, c)
@@ -788,6 +792,23 @@ export interface UploadTally {
   failed: number
 }
 
+/** One task's traffic with the remotes this run, by its key. */
+export interface RemoteKeyTraffic {
+  /** Its uploads queued or running. */
+  uploading: number
+  /** An upload of it landed on a remote. */
+  landed: boolean
+  /** Each distinct remote read or write of it that failed: `upload: <message>`. */
+  failures: string[]
+}
+
+/** The run's remote traffic per key: what the footer's remote part counts, task by task. */
+export interface RemoteTraffic {
+  /** Uploads queued or running across every remote. */
+  inFlight: number
+  readonly keys: Map<string, RemoteKeyTraffic>
+}
+
 export class Cache implements CacheLayer {
   /** This IS the local layer — there is nothing slower behind it. */
   readonly hasRemote = false
@@ -797,6 +818,8 @@ export class Cache implements CacheLayer {
    * so the run can report them without a method on the layer seam.
    */
   readonly uploads: UploadTally = { count: 0, bytes: 0, ms: 0, failed: 0 }
+  /** The same remotes' traffic per key, filled by the same `LayeredCache`. */
+  readonly traffic: RemoteTraffic = { inFlight: 0, keys: new Map() }
 
   private readonly db: Database
   private readonly insertEntry: ReturnType<Database['prepare']>
@@ -1471,11 +1494,13 @@ export class Cache implements CacheLayer {
   }
 
   key(input: CacheKeyInput): Promise<string> {
+    const hashFile = (f: string): Promise<string> => this.hashFile(f)
     return foldKey(
       input,
-      (f) => this.hashFile(f),
+      hashFile,
       (f) => this.relFor(input.workspaceRoot, f),
       (v) => this.digestValue(v),
+      (link) => behindLink(link, hashFile),
     )
   }
 
@@ -1758,9 +1783,14 @@ export class Cache implements CacheLayer {
 
   private async hasEntry(hash: string): Promise<'local' | 'remote' | null> {
     if (!this.read) return null
+    return this.storedHere(hash) ? 'local' : null
+  }
+
+  /** The index row and its artifact are both here, whatever the run may read. */
+  private storedHere(hash: string): boolean {
     const row = this.entryExists.get(hash) as { inline_at: number | null } | null
-    if (row === null) return null
-    return row.inline_at !== null || existsSync(this.tarPath(hash)) ? 'local' : null
+    if (row === null) return false
+    return row.inline_at !== null || existsSync(this.tarPath(hash))
   }
 
   // Local cache has no slower layer to warm from — prefetch is a no-op.
@@ -2054,8 +2084,6 @@ export class Cache implements CacheLayer {
     entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
-    /** See `CacheLayer.save`. */
-    skipLocalWrite?: boolean
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
     inputComponents?: readonly TaskInputRow[]
@@ -2080,7 +2108,9 @@ export class Cache implements CacheLayer {
     // still uploads to remote — it calls `packArtifact` itself to get
     // the bytes, since there's no local artifact to read off disk.
     if (!this.write) return
-    if (args.skipLocalWrite === true) return
+    // A cache that reads saves only on a miss. One that does not (`--force`)
+    // re-executes a key it may hold: that entry is kept as it is.
+    if (!this.read && this.guard(() => this.storedHere(args.hash))) return
     // The cache directory is the constructor's (`mkdirSync`, with a
     // refusal recorded for `assertWritable`); re-creating it here and
     // again in `writeArtifactAndIndex` cost every save two thread-pool
@@ -2631,6 +2661,9 @@ export class Cache implements CacheLayer {
   recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
     return this.guard(() => this.history.recordRunBundle(bundle))
   }
+  recordRemoteErrors(runId: string, errors: readonly (readonly [string, string])[]): void {
+    return this.guard(() => this.history.recordRemoteErrors(runId, errors))
+  }
   stats(opts: CacheStatsOptions = {}): CacheStats {
     return this.guard(() => this.statsOf(opts))
   }

package/src/cache/file-hashes.ts

@@ -163,14 +163,10 @@ export class FileHashStore {
       // a more useful error.
       return await this.hashFileFromDisk(filePath)
     }
-    // A symlink folds as git folds it: the blob of its TARGET STRING, which
-    // is its mode-120000 index OID. Not the bytes behind it — a link to a
-    // directory has none, a dangling one has none, and a link to a file
-    // outside the project would fold bytes `git diff` and `--affected`
-    // cannot see. A link to a file inside the project tracks that file's
-    // content only when the file matches the task's globs too. No
-    // memo: readlink is one syscall, and the row would be keyed on the
-    // link's own stat, not its target's.
+    // A symlink's identity is git's: the blob of its TARGET STRING, its
+    // mode-120000 index OID, so a retarget moves it. What it points to
+    // folds after it (linked-inputs.ts). No memo: readlink is one syscall,
+    // and the row would be keyed on the link's own stat, not its target's.
     if (st.isSymbolicLink()) {
       return fileIdentity(
         '120000',
@@ -257,12 +253,11 @@ export class FileHashStore {
     for (const p of paths) {
       if (stats.has(p) || out.has(p)) continue
       try {
-        // lstat, not stat: `hashFile` folds a symlink as git folds it —
+        // lstat, not stat: `hashFile` identifies a symlink as git does —
         // the blob of its TARGET STRING — and this form promises the same
         // digest. Following the link here instead hashed the target's
         // BYTES, so the same path identified differently depending on
-        // which entry point the caller used, and the batch folded bytes
-        // `git diff` and `--affected` cannot see.
+        // which entry point the caller used.
         const st = lstatSync(p)
         if (st.isSymbolicLink()) {
           // No memo, for `hashFile`'s reason: the row would be keyed on
@@ -367,7 +362,7 @@ export class FileHashStore {
       if (!isPermissionError(err)) throw err
       throw new UserError(
         `${filePath} is not readable by this user (${err.code}), and vx reads it to derive a ` +
-          'cache key. Make it readable, or, for a task input, take it out of cache.inputs.files.',
+          'cache key. Make it readable, or, for a task input, take it out of inputs.files.',
       )
     }
     return this.hashBytes(bytes, filePath)

package/src/cache/fs-clock.ts

@@ -0,0 +1,62 @@
+// How far the workspace's file system clock runs behind this process's. A
+// racy window (`racyWindowMs`) compares a file's stamp, on the clock of the
+// file system that holds it, with a moment vx read from `Date.now()`, as if
+// they were one clock. A file system behind it (a WSL2 VM drifted from the
+// Windows host that stamps `/mnt/c`, a Docker Desktop bind mount, an NFS
+// server) dated an edit made while a command ran before the command, and the
+// entry filed the edit's output under the key of the bytes before it. A
+// clock ahead only makes a stamp look newer, which every window reads the
+// safe way.
+
+import { mkdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * A lag at or under this is the kernel's coarse tick, which stamps a write
+ * up to ~10 ms behind `Date.now()` on every box and which each window
+ * already holds; widening by it withheld saves after a fast upstream.
+ */
+const FS_CLOCK_TICK_MS = 20
+
+let lagMs = 0
+
+/** The lag every racy window is widened by: 0 unless measured past the tick. */
+export function fsClockLag(): number {
+  return lagMs
+}
+
+/** Widen every racy window by `ms`, when it is past the tick. */
+export function setFsClockLag(ms: number): void {
+  lagMs = ms > FS_CLOCK_TICK_MS ? ms : 0
+}
+
+/**
+ * What a stamp's own precision may hide (see `racyWindowMs`): a stamp with
+ * no sub-second part stands for any moment in its second, an even one for
+ * FAT's two.
+ */
+export function stampGrainMs(stampMs: number): number {
+  if (stampMs % 2000 === 0) return 2000
+  return stampMs % 1000 === 0 ? 1000 : 0
+}
+
+/**
+ * Measure the lag from a file written and removed in `dir` (the run's cache
+ * dir: on the workspace's file system by default, and ignored by git and
+ * `vx watch`), and apply it. Once a run: one write, one stat, one unlink. A
+ * directory that cannot take the file measures no lag.
+ */
+export function measureFsClockLag(dir: string): void {
+  const stamp = path.join(dir, `.vx-clock-${process.pid}`)
+  let ms = 0
+  try {
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(stamp, '')
+    const at = statSync(stamp).mtimeMs
+    ms = Date.now() - at - stampGrainMs(at)
+    unlinkSync(stamp)
+  } catch {
+    // unmeasured: no lag, as before
+  }
+  setFsClockLag(ms)
+}

package/src/cache/git-inputs.ts

@@ -289,6 +289,12 @@ export class GitFilesCache extends Map<string, readonly string[]> {
    * a cache no enumeration filled; its OIDs are then re-checked by content.
    */
   enumeratedAtMs: number | undefined
+  /**
+   * The declared outputs (root-relative globs) git ignores whole, asked
+   * once per run beside the enumeration: no key reads them, so a reader
+   * beside their producer keys up front (`dependsOnSiblingOutputs`).
+   */
+  ignoredOutputs: ReadonlySet<string> = new Set()
 
   get undecodableNames(): ReadonlySet<string> {
     return this.undecodable
@@ -1256,7 +1262,7 @@ function stripPrefixFromSet(paths: Set<string>, prefix: string): Set<string> {
  * directly — clean-tree input hashing costs zero reads/stats/SQLite.
  *
  * `workspaceWide`: set when any loaded task declares
- * `cache.inputs.workspaceFiles`. Disables pathspec scoping (those
+ * `inputs.workspaceFiles`. Disables pathspec scoping (those
  * globs must see every file from the root) and additionally stores a
  * workspace-wide partition keyed by `workspaceRoot` (files + trusted
  * OIDs), which `resolveWorkspaceFiles` consumes. When false, the
@@ -1833,7 +1839,7 @@ export async function applyGitEnumeration(
     // workspace's git holds as ONE entry (a gitlink, `dir/` when untracked)
     // — is listed through its own git above (`expandNestedRepos`), but under
     // a pathspec naming a project inside it the workspace's git lists
-    // nothing at all; so is a directory ignored outright. Storing the empty slice made the key never move: `cache.inputs
+    // nothing at all; so is a directory ignored outright. Storing the empty slice made the key never move: `inputs
     // matched no files`, then a stale hit under a green run once the source
     // changed (2026-09-16). No partition instead: `resolveFiles` spawns
     // `git ls-files` in the project's own directory, which a nested

package/src/cache/index.ts

@@ -21,6 +21,7 @@ export {
   KEYED_RUNS_SQL,
   parseCachePolicy,
   type RunRecord,
+  type TaskInputComponent,
   type TaskInputRow,
   WORKSPACE_OUTPUT_PREFIX,
   type OutputDirRow,
@@ -33,6 +34,8 @@ export {
   vxCacheEntries,
 } from './cache.js'
 export { ABSENT_INPUT, absentOr, CACHE_VERSION } from './key-fold.js'
+export { measureFsClockLag, setFsClockLag } from './fs-clock.js'
+export { filesBehind } from './linked-inputs.js'
 export {
   addedInput,
   type InputListing,
@@ -40,6 +43,7 @@ export {
   committedFiles,
   cleanWorkspaceOutputs,
   declaresInput,
+  namedOutright,
   workspaceFilesReachInto,
   resolveInputs,
   resolveOutputs,
@@ -69,14 +73,13 @@ export {
   type BlobSizeMemo,
 } from './git-inputs.js'
 export { LayeredCache, type RemoteCacheLayer } from './layered-cache.js'
+export type { ResolvedRemote } from './remote-lane.js'
 export { ScopedCache } from './scoped-cache.js'
 export {
   absentPluginCache,
   pluginCache,
   PLUGIN_ENTRY_MAX_BYTES,
   type PluginCache,
-  type PluginCacheRemote,
 } from './plugin-cache.js'
 export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
-export { ChainedCache } from './chained-cache.js'
 export { branchSource } from './run-history.js'