@vzn/vx 0.0.637 → 0.0.639

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.637",
+  "version": "0.0.639",
   "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.637",
-    "@vzn/vx-linux-arm64": "0.0.637",
-    "@vzn/vx-darwin-x64": "0.0.637",
-    "@vzn/vx-darwin-arm64": "0.0.637"
+    "@vzn/vx-linux-x64": "0.0.639",
+    "@vzn/vx-linux-arm64": "0.0.639",
+    "@vzn/vx-darwin-x64": "0.0.639",
+    "@vzn/vx-darwin-arm64": "0.0.639"
   },
   "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/plan.json

@@ -45,8 +45,8 @@
             "required": ["kind"],
             "properties": {
               "kind": {
-                "enum": ["input", "project", "package", "named", "selected"],
-                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
+                "enum": ["input", "project", "workspace", "package", "named", "selected"],
+                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; workspace: a workspace-wide file (the workspace config, a root file a plugin claims) changed; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
               },
               "file": { "type": "string", "description": "the changed file, workspace-relative" },
               "project": { "type": "string", "description": "the changed package (kind package)" },

package/skills/vx/SKILL.md

@@ -15,22 +15,33 @@ 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
 tasks it found.
 
+## After editing a config
+
+```sh
+vx lock   # after any edit to a vx.config.ts or .vx/workspace.ts
+```
+
+A run reads every config from `.vx/projects.lock.json`, never the files:
+a task you add, or an edit to one, does nothing until `vx lock`. Commit
+the lock with the config.
+
 ## Look before running
 
 ```sh
-vx show --format json                          # projects, their tasks and dependencies
+vx show --format json                          # projects and their tasks
+vx show app --format json                      # one project's tasks as a run reads them
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
@@ -94,6 +105,8 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 
 ## Install
 
-`npx skills add vznjs/vx/packages/vx/skills/vx` installs this skill. To match the vx a workspace
+`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/bin.ts

@@ -46,7 +46,7 @@ async function main(): Promise<void> {
     process.exitCode = code
   } catch (err) {
     const {
-      configErrorFrame,
+      detectColors,
       errorCode,
       errorDocument,
       fsRefusalHint,
@@ -55,6 +55,8 @@ async function main(): Promise<void> {
       isUserError,
       maskedLine,
       OUT_OF_FDS_HINT,
+      refusalNotice,
+      ui,
       wantsJson,
     } = await import('./util/index.js')
     // A plugin's failure quotes what it was told (a remote's reply, a
@@ -66,12 +68,16 @@ async function main(): Promise<void> {
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
     if (isUserError(err)) {
-      // A message that already names the tool (`vx why: …`, thrown by a verb
-      // that wants its own name in the line) is printed as it is; prefixing
-      // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
-      // A config refusal names its line and shows it.
-      const m = configErrorFrame(err.message, process.cwd()) ?? err.message
-      say(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+      // A message that names its verb (`vx why: …`) is that verb's; any
+      // other is the verb typed. A config refusal shows its line.
+      const named = /^(vx [a-z][\w-]*): /.exec(err.message)
+      const typed = /^[a-z][\w-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
+      const block = refusalNotice(
+        named?.[1] ?? typed,
+        named === null ? err.message : err.message.slice(named[0].length),
+        err.parts,
+      )
+      process.stderr.write(maskedLine(ui.render([block], detectColors(process.stderr))))
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {

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'
@@ -303,17 +304,25 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        unchanged.
 //   v36: the store's task_durations: each executed success's time, tagged
 //        by branch, read by the forecast. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v36'
+//   v37: the store's plugin_blobs (a plugin's `ctx.cache`) and one
+//        'remote' task_durations row per (sha, task). The cache KEY is
+//        unchanged.
+//   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.
+//   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)
@@ -333,6 +342,9 @@ const STORE_TABLES = [
   'output_files',
   'entry_stdout',
   'task_durations',
+  'task_outcomes',
+  'blob_sizes',
+  'plugin_blobs',
   'store_meta',
   'entries',
 ]
@@ -779,6 +791,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
@@ -788,6 +817,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']>
@@ -1030,7 +1061,7 @@ export class Cache implements CacheLayer {
             // keeps it so).
             if (found !== undefined) {
               this.db.exec(
-                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.store_meta;',
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta;',
               )
             }
             // The tables land under the same write lock as the stamp: made
@@ -1737,11 +1768,26 @@ export class Cache implements CacheLayer {
     return this.guard(() => this.hasEntry(hash))
   }
 
+  /**
+   * The subset of `hashes` this store holds, `has` for each: the prefetch
+   * pass asks the remote only about the rest (M, 2026-10-15).
+   */
+  async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    const out = new Set<string>()
+    for (const hash of hashes) if ((await this.has(hash)) === 'local') out.add(hash)
+    return out
+  }
+
   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.
@@ -2035,8 +2081,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[]
@@ -2061,7 +2105,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
@@ -2612,6 +2658,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/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

package/src/cache/index.ts

@@ -15,11 +15,13 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  formatCachePolicy,
   FULL_CACHE_POLICY,
   type InvocationRecord,
   KEYED_RUNS_SQL,
   parseCachePolicy,
   type RunRecord,
+  type TaskInputComponent,
   type TaskInputRow,
   WORKSPACE_OUTPUT_PREFIX,
   type OutputDirRow,
@@ -47,7 +49,6 @@ export {
   type ProjectFilesCache,
   type WorkspaceFilesCache,
   cleanOutputPaths,
-  anyUntouched,
   ownOutputsSince,
   ownWorkspaceOutputsSince,
   stampOutputs,
@@ -69,6 +70,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 { ChainedCache } from './chained-cache.js'
+export {
+  absentPluginCache,
+  pluginCache,
+  PLUGIN_ENTRY_MAX_BYTES,
+  type PluginCache,
+} from './plugin-cache.js'
+export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { branchSource } from './run-history.js'

package/src/cache/inputs.ts

@@ -81,7 +81,6 @@ const ALWAYS_IGNORE = [
   '**/.git/**',
   // vx's machine-local state; the workspace config beside it is a source.
   '**/.vx/cache/**',
-  '**/*.tsbuildinfo',
   '**/.vx/projects.lock.json',
   // `vx lock`'s review copy of a project's resolved config: the config is
   // keyed already, and a re-lock must not move every `**` reader's key.
@@ -1018,29 +1017,6 @@ function changedSince(
   return kept < before.size ? undefined : own
 }
 
-/**
- * Is any file `before` stamped still there, unchanged? Under
- * `cache.outputs.clean: false` such a file is one the run found and never
- * wrote, so no entry may claim it as the run's output.
- */
-export function anyUntouched(before: ReadonlyMap<string, OutputStamp>): boolean {
-  for (const [f, was] of before) {
-    try {
-      const st = lstatSync(f)
-      if (
-        st.size === was.size &&
-        st.mtimeMs === was.mtimeMs &&
-        st.ino === was.ino &&
-        st.ctimeMs === was.ctimeMs
-      )
-        return true
-    } catch {
-      // Removed by the run: nothing of it is left to claim.
-    }
-  }
-  return false
-}
-
 /**
  * Up to this many paths, a clean removes synchronously: the threadpool round
  * trip per `rm`/`rmdir` cost more than the unlink itself, 0.30 ms against

package/src/cache/layer.ts

@@ -1,5 +1,5 @@
 // The cache layer CONTRACT and its records — what every cache implementation
-// honours (`Cache`, `LayeredCache`, `ChainedCache`, a plugin's remote layer) and
+// honours (`Cache`, `LayeredCache`, a plugin's remote layer) and
 // the shapes that cross it: the key input, entries, run-history rows, output
 // fingerprints, stats, prune options. No implementation lives here; the one
 // reference to `Cache` below is a type (the local handle a layer may wrap).
@@ -208,6 +208,8 @@ export interface RunRecord {
   timedOut?: true
   sandboxViolations?: number
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /** Each remote read or write of its key that failed, `upload: <message>`, `; `-joined (v40). */
+  remoteError?: string
 }
 
 /**
@@ -221,7 +223,7 @@ export interface InvocationRecord {
   command: string
   /** JSON-serialized `string[]` of the requested task names. */
   requestedTasks: string
-  /** Compact policy flags, e.g. `'lR,lW,rR,rW'` (an axis omitted = off). */
+  /** The `--cache-policy` spec, e.g. `'local:rw,remote:r'` (a flag omitted = off). */
   cachePolicy: string
   concurrency: number
   flow: 'focused' | 'broad' | null
@@ -247,8 +249,18 @@ export interface InvocationRecord {
   os: string | null
   arch: string | null
   vxVersion: string
-  /** JSON object `{k:v}` of `--tag` pairs. */
-  tags: string
+}
+
+/**
+ * One cache-key component as `key()` folded it, the `captureInto` row.
+ * Persisted on a miss (`TaskInputRow`) so a later run can diff its inputs
+ * against this one (the Tier-3 "why did this re-run?" moat); a hit saves
+ * nothing, so the warm path is free.
+ */
+export interface TaskInputComponent {
+  kind: string
+  name: string
+  hash: string
 }
 
 /**
@@ -544,12 +556,25 @@ export interface CacheLayer {
    * batch omits it and the prefetch pass falls back to per-hash GETs.
    */
   remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  /**
+   * The subset of `hashes` the local store already holds. The prefetch
+   * pass probes the remote only for the rest, so a run the local cache
+   * answers makes no remote call. Absent reads as "none held".
+   */
+  localHasMany?(hashes: readonly string[]): Promise<Set<string>>
   /**
    * Record that the remote has NO artifact for each of `hashes` (from a
    * batch probe), so a later `get`/`prefetch` short-circuits to a miss with
    * no round-trip. Only meaningful with `hasRemote`.
    */
   markRemoteAbsent?(hashes: Iterable<string>): void
+  /**
+   * The run's up-front keys, for each remote the run writes but does not
+   * read (`--force`): one batch probe in the background, and an upload of
+   * a key the remote already holds is skipped. Only meaningful with
+   * `hasRemote`.
+   */
+  probeBeforeUpload?(hashes: Promise<readonly string[]>): void
   /**
    * Resolve once every background write-through upload settles. The
    * orchestrator awaits it before `close()` — an upload reading layer state
@@ -557,6 +582,8 @@ export interface CacheLayer {
    * uploads synchronously (or not at all) omits it.
    */
   drainUploads?(): Promise<void>
+  /** The run was stopped: start no more uploads, and let `drainUploads` resolve now. */
+  stopUploads?(): void
   key(input: CacheKeyInput): Promise<string>
   get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
   /**
@@ -574,7 +601,7 @@ export interface CacheLayer {
    * artifact read, no remote download, no local ingest, no accessed_at
    * bump (on the remote side the layer decides the call: an HTTP HEAD, or
    * REAPI's `getActionResult` + `findMissingBlobs`). Planning
-   * (`--dry` / `--graph`) predicts hits with this instead of `get` so a
+   * (`--dry`) predicts hits with this instead of `get` so a
    * dry run can't pull N artifacts over the network. Remote errors
    * degrade to `null` — an existence probe never fails anything.
    */
@@ -664,13 +691,6 @@ export interface CacheLayer {
     entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
-    /**
-     * Set only by ChainedCache when an EARLIER layer in the chain already
-     * wrote this artifact to the same local handle: the local pack + write
-     * is skipped and only the layer's remote side acts. A layer with no
-     * remote side treats it as a full no-op.
-     */
-    skipLocalWrite?: boolean
     /**
      * Resolved `outputs.workspaceFiles` (absolute paths) + the root
      * they're relative to. Packed under `workspace-outputs/<rel>`.