@vzn/vx 0.0.473 → 0.0.474

package/package.json

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

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

@@ -18,8 +18,11 @@ function settledState(abs: string): bigint {
     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,