@vzn/vx 0.0.473 → 0.0.475

package/package.json

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

package/src/cli/completions.ts

@@ -70,7 +70,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
         '  esac',
         '}',
-        'compdef _vx vx',
+        // Autoloaded from $fpath (the `#compdef` file), this body runs on
+        // the first Tab: it must complete then, not only define `_vx`, or
+        // that Tab rings the bell. Sourced, it registers instead.
+        'if [[ "${funcstack[1]}" == _vx ]]; then',
+        '  _vx "$@"',
+        'else',
+        '  compdef _vx vx',
+        'fi',
         '',
       ].join('\n')
     case 'fish':

package/src/cli/plugin-commands.ts

@@ -8,8 +8,9 @@
 // before this is asked, so a plugin cannot shadow `run`.
 
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
-import { findWorkspaceRoot } from '../workspace/index.js'
-import { loadCliWorkspace } from './workspace-config.js'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { findWorkspaceRoot, WORKSPACE_CONFIG_FILENAMES } from '../workspace/index.js'
 import { machineParallelism, maskedLine } from '../util/index.js'
 
 export interface ResolvedPluginCommand {
@@ -52,8 +53,14 @@ async function workspacePlugins(
   } catch {
     return null
   }
+  // Plugins are declared only in a workspace file. Without one, the load
+  // below is the orchestrator's import graph (~50 ms) for an empty list,
+  // paid by `vx help` and by the `vx completions` a shell sources at start.
+  if (!WORKSPACE_CONFIG_FILENAMES.some((f) => existsSync(path.join(workspaceRoot, f))))
+    return { workspaceRoot, cacheDir: '', concurrency: 0, plugins: [] }
   let ws
   try {
+    const { loadCliWorkspace } = await import('./workspace-config.js')
     ws = await loadCliWorkspace(workspaceRoot)
   } catch (err) {
     return { loadError: err instanceof Error ? err.message : String(err) }

package/src/cli/upgrade.ts

@@ -12,7 +12,9 @@
 // Named `upgrade` (not `update`) per CLI convention: bun upgrade,
 // deno upgrade — "update" is what package managers do to indexes.
 
-import { chmod, chown, link, rename, rm, stat } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { access, chmod, chown, link, rename, rm, stat } from 'node:fs/promises'
+import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
 import { VERSION } from '../version.js'
@@ -218,6 +220,15 @@ export async function replaceBinary(
   sha256: string,
   starts?: (dest: string) => boolean,
 ): Promise<void> {
+  // The swap writes beside the binary: a directory this user cannot write
+  // (a root-owned /usr/local/bin) failed at the rename, the whole release
+  // downloaded for nothing, and the hint named npm, which this binary is not.
+  const dir = path.dirname(dest)
+  await access(dir, constants.W_OK).catch((err: NodeJS.ErrnoException) => {
+    throw new UserError(
+      `vx upgrade: cannot write to ${dir} (${err.code ?? err.message}), where this vx lives — nothing downloaded; re-run as a user who can (sudo vx upgrade), or install vx somewhere you can write`,
+    )
+  })
   const res = await fetchOrRefuse(url, { redirect: 'follow' }, 'download the release asset')
   if (!res.ok) {
     throw new UserError(
@@ -258,8 +269,7 @@ export async function replaceBinary(
     if (kept) await rm(old, { force: true })
     const msg = err instanceof Error ? err.message : String(err)
     throw new UserError(
-      `vx upgrade: could not replace ${dest} (${msg}) — ` +
-        `check permissions, or reinstall with npm install -g @vzn/vx`,
+      `vx upgrade: could not replace ${dest} (${msg}) — nothing replaced; check the permissions of ${dest} and its directory`,
     )
   }
   if (starts === undefined || starts(dest)) {

package/src/cli/watch-judge.ts

@@ -13,13 +13,19 @@ const ABSENT = -1n
 function settledState(abs: string): bigint {
   let st: fs.Stats
   try {
+    // A link is its target string, as the key folds it: following it saw
+    // a retarget to equal bytes as "the same" and ran nothing.
+    if (fs.lstatSync(abs).isSymbolicLink()) return xxh3(`link:${fs.readlinkSync(abs)}`)
     st = fs.statSync(abs)
   } catch {
     return ABSENT
   }
   if (!st.isDirectory()) {
+    // The mode too: the key reads it (an executable bit can change what a
+    // task does), and with the bytes alone a judged file's `chmod -x`
+    // settled to "the same" and ran nothing.
     try {
-      return xxh3(fs.readFileSync(abs))
+      return xxh3(`${xxh3(fs.readFileSync(abs))}:${st.mode & 0o7777}`)
     } catch {
       return ABSENT
     }

package/src/exec/executor.ts

@@ -223,6 +223,23 @@ export interface TaskExecutor {
   execute(req: ExecuteRequest): Promise<ExecuteResult>
 }
 
+/**
+ * What a remote executor rejects with when it gives a task back: core runs
+ * the same request on the local floor and says `reason` once (a remote that
+ * never started it, B-100). A task placed `remote: 'only'` must not run
+ * here, so it fails naming `reason` instead. Matched by name, as
+ * `isUserError` is: a plugin's `@vzn/vx` can be another copy of this class.
+ */
+export function executorFallback(reason: string): Error {
+  const err = new Error(reason)
+  err.name = 'ExecutorFallback'
+  return err
+}
+
+export function isExecutorFallback(err: unknown): err is Error {
+  return err instanceof Error && err.name === 'ExecutorFallback'
+}
+
 /**
  * The result an executor resolves with is a plugin's, so its shape is a
  * boundary: a plugin that resolved `{}` met `res.violations` in core and

package/src/exec/index.ts

@@ -41,6 +41,8 @@ export { isLocalExecutor, localExecutor } from './local-executor.js'
 export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'
 export {
   assertExecuteResult,
+  executorFallback,
+  isExecutorFallback,
   selectExecutor,
   type ExecuteRequest,
   type ExecuteResult,

package/src/index.ts

@@ -171,6 +171,9 @@ export type {
 // (`runCommand` / `runSandboxed`, the local executor's own primitives, left
 // the façade 2026-09-10: no executor plugin built on them — `@vzn/vx-reapi`
 // speaks a wire — and a seam with no consumer is a special case in waiting.)
+// A remote executor gives a task back to the local floor by rejecting with
+// this (B-100): core runs it here and says why once.
+export { executorFallback } from './exec/index.js'
 export type {
   ExecuteRequest,
   ExecuteResult,

package/src/orchestrator/execute-task.ts

@@ -25,6 +25,8 @@ import {
   wrapSandboxedCommand,
   signalExitCode,
   isLocalExecutor,
+  isExecutorFallback,
+  localExecutor,
   type CaptureConfig,
   type ExecuteRequest,
   assertExecuteResult,
@@ -45,6 +47,7 @@ import {
   secretMask,
   secretNamed,
   span,
+  UserError,
 } from '../util/index.js'
 import { forwardedSignal, SIGNAL_SHUTDOWN_GRACE_MS } from './signals.js'
 import { executorLabel, nameExecutorFailure } from './plugin-host.js'
@@ -895,7 +898,23 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         assertExecuteResult(args.executor.name, node.id, r)
         return r
       })
-      .catch(async (raw: unknown) => {
+      .catch(async (thrown: unknown) => {
+        let raw = thrown
+        // A remote that gives the task back (it never started it): run it on
+        // the local floor with a request of its own, so its timeout counts
+        // from now. `remote: 'only'` keeps it off this machine: refused.
+        if (isExecutorFallback(raw) && args.executor.remote === true) {
+          const why = secrets?.mask(raw.message) ?? raw.message
+          if (remoteOnly) {
+            raw = new UserError(`${why}, and remote: 'only' keeps it off this machine`)
+          } else {
+            log.status(`[vx] ${node.id}: ${why} — running it here`)
+            clearTimeout(timeoutTimer)
+            const local = await localExecutor().execute(await buildRequest())
+            assertExecuteResult('local', node.id, local)
+            return local
+          }
+        }
         const err = nameExecutorFailure(args.executor, raw)
         // A remote executor's message carries the server's own text, which
         // may echo the env it was sent: masked here, where it is printed,

package/src/workspace/config-schema.ts

@@ -484,9 +484,16 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
       const inputs = (cache as { inputs?: unknown }).inputs
       const outputs = (cache as { outputs?: unknown }).outputs
-      if (!inputs || typeof inputs !== 'object') {
+      // A present field of the wrong shape (`outputs: 'dist'`) was told it
+      // was missing; an array is named in `assertKnownFields`.
+      if (inputs === undefined || inputs === null) {
         throw new UserError(`${where}.cache.inputs is required when \`cache\` is set`)
       }
+      if (typeof inputs !== 'object') {
+        throw new UserError(
+          `${where}.cache.inputs must be an object — \`inputs: { files: [...] }\``,
+        )
+      }
       assertKnownFields(inputs, CACHE_INPUT_FIELDS, `${where}.cache.inputs`)
       if (!Array.isArray((inputs as { files?: unknown }).files)) {
         throw new UserError(`${where}.cache.inputs.files must be an array of glob strings`)
@@ -520,9 +527,14 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
           }
         }
       }
-      if (!outputs || typeof outputs !== 'object') {
+      if (outputs === undefined || outputs === null) {
         throw new UserError(`${where}.cache.outputs is required when \`cache\` is set`)
       }
+      if (typeof outputs !== 'object') {
+        throw new UserError(
+          `${where}.cache.outputs must be an object — \`outputs: { files: [...] }\``,
+        )
+      }
       assertKnownFields(outputs, CACHE_OUTPUT_FIELDS, `${where}.cache.outputs`)
       const outFiles = (outputs as { files?: unknown }).files
       if (!Array.isArray(outFiles)) {