@vzn/vx 0.0.643 → 0.0.644

package/src/cache/file-hashes.ts

@@ -14,9 +14,6 @@ import { fileIdentity, repoFacts } from './git-inputs.js'
 import { FILE_HASH_RACY_MS, isIndexFull, racyWindowMs } from './layer.js'
 import { isPermissionError, UserError } from '../util/index.js'
 
-const FILE_HASHES_SWEPT_AT = 'file_hashes_swept_at'
-const DAY_MS = 24 * 60 * 60 * 1000
-
 export class FileHashStore {
   private readonly selectFileHash: ReturnType<Database['prepare']>
   private readonly upsertFileHash: ReturnType<Database['prepare']>
@@ -62,22 +59,13 @@ export class FileHashStore {
    * path) keeps its row forever otherwise, and `cache.db` grows with every
    * path ever hashed. A hit does not refresh `seen_at` (a write per file
    * per run), so a file unchanged for the window loses its row too and is
-   * read once more; a dropped row is only a memo miss. The scan costs
-   * 8 ms at 100,000 rows, so it runs once a day, on its own clock in
-   * `schema_meta` (item 1082).
+   * read once more; a dropped row is only a memo miss.
    */
-  pruneOlderThan(cutoff: number, now: number = Date.now()): void {
-    const last = this.db
-      .prepare('SELECT value FROM schema_meta WHERE key = ?')
-      .get(FILE_HASHES_SWEPT_AT) as { value: string } | null
-    if (last !== null && now - Number(last.value) < DAY_MS) return
+  pruneOlderThan(cutoff: number): void {
     this.db.transaction(() => {
       this.db.prepare('DELETE FROM file_hashes WHERE seen_at < ?').run(cutoff)
       this.db.prepare('DELETE FROM blob_sizes WHERE seen_at < ?').run(cutoff)
       this.db.prepare('DELETE FROM blob_verdicts WHERE seen_at < ?').run(cutoff)
-      this.db
-        .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
-        .run(FILE_HASHES_SWEPT_AT, String(now))
     })()
   }
 

package/src/cache/fold-memo.ts

@@ -43,16 +43,20 @@ export class FoldMemo {
     if (this.write) this.dirty.set(taskId, { probe, key })
   }
 
-  /** Write the folds this run made; rows a run has not rewritten for `cutoff` go. */
-  flush(cutoff: number, now: number = Date.now()): void {
+  /** Write the folds this run made. */
+  flush(now: number = Date.now()): void {
     if (this.dirty.size === 0) return
     const upsert = this.db.prepare(
       'INSERT OR REPLACE INTO fold_memo(task_id, probe, key, seen_at) VALUES (?, ?, ?, ?)',
     )
     this.db.transaction(() => {
       for (const [taskId, r] of this.dirty) upsert.run(taskId, r.probe, r.key, now)
-      this.db.prepare('DELETE FROM fold_memo WHERE seen_at < ?').run(cutoff)
     })()
     this.dirty.clear()
   }
+
+  /** Rows no run has rewritten since `cutoff`. */
+  prune(cutoff: number): void {
+    this.db.prepare('DELETE FROM fold_memo WHERE seen_at < ?').run(cutoff)
+  }
 }

package/src/cache/index.ts

@@ -8,6 +8,8 @@ export {
   applyCacheFlags,
   ArtifactVanishedError,
   Cache,
+  DEFAULT_STORE,
+  type StoreOptions,
   type CacheFlags,
   type CacheEntry,
   type CacheKeyInput,
@@ -85,6 +87,7 @@ export {
   type RemoteKey,
   type RemoteOpenContext,
 } from './layered-cache.js'
+export { networkConcurrency } from './remote-lane.js'
 export type { ResolvedRemote } from './remote-lane.js'
 export { BranchScope } from './scoped-cache.js'
 export {

package/src/cache/key-fold.ts

@@ -117,7 +117,10 @@ import type { CacheKeyInput } from './layer.js'
 // v46: vx's names are reserved only at the project root; a v45 artifact
 // left out a build's own `dist/.git/**`, `dist/.vx/**` and nested
 // `vx.lock.json` (Growth's parity, 2026-10-17).
-export const CACHE_VERSION = 'vx-cache-v46'
+// v47: the local store keeps plain files (`cache.store`).
+// v48: a task glob is standard again (M, 2026-10-18): `app/[id]/page.js` is
+// a class, and a v47 entry under its unchanged key holds the literal route.
+export const CACHE_VERSION = 'vx-cache-v48'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/layer.ts

@@ -493,8 +493,8 @@ export class CorruptArtifactError extends Error {
 
 /**
  * `restoreOutputs` found no artifact where the probe found one: it was
- * removed in between — a `vx cache clean` in another shell, or the
- * `cacheRetention` of another workspace sharing the cache directory. The
+ * removed in between — a `vx cache clean` in another shell, or one for
+ * another workspace sharing the cache directory. The
  * bytes are not wrong, they are gone, so the entry is a MISS and the task
  * runs (execute-task.ts); nothing about the cache needs throwing away.
  * Also thrown, with its `reason`, for an artifact whose bytes ARE wrong
@@ -510,8 +510,7 @@ export class ArtifactVanishedError extends Error {
     cause?: unknown,
   ) {
     super(
-      reason ??
-        `its cache artifact ${hash} vanished before the restore (a prune or another run's retention)`,
+      reason ?? `its cache artifact ${hash} vanished before the restore (a vx cache clean)`,
       cause === undefined ? undefined : { cause },
     )
     this.name = 'ArtifactVanishedError'
@@ -576,6 +575,12 @@ export interface CacheLayer {
    * `hasRemote`.
    */
   probeBeforeUpload?(hashes: Promise<readonly string[]>): void
+  /**
+   * The run's batch probe starts when `started` settles: until then a pull
+   * waits, so a lookup that lands first does not GET a key the probe is
+   * about to call absent. Only meaningful with `hasRemote`.
+   */
+  probeFirst?(started: Promise<void>): void
   /** `taskId`'s key is `hash`: a scoped run picks each remote key by its task (`BranchScope`). */
   noteKey?(taskId: string, hash: string): void
   /**

package/src/cache/layered-cache.ts

@@ -175,6 +175,17 @@ export class LayeredCache implements CacheLayer {
    */
   private readonly inflight = new Map<string, Promise<boolean>>()
 
+  /**
+   * Hashes a batch probe is asking about, each resolving whether a pull may
+   * still find it (false: no remote holds it). A `get` that lands while the
+   * probe is out waits for its answer instead of spending a GET on a key
+   * the probe is about to call absent.
+   */
+  private readonly probing = new Map<string, Promise<boolean>>()
+
+  /** Settles once the run's batch probe has started (`probeFirst`); a pull waits on it. */
+  private probeStarted: Promise<void> | null = null
+
   /**
    * Hashes whose local artifact was materialized FROM a remote this run
    * (by `prefetch` or `get`'s read-through). A later `get` finds them as
@@ -192,9 +203,11 @@ export class LayeredCache implements CacheLayer {
     remotes: readonly ResolvedRemote[],
     /** The run's branch scope: it picks each remote key; the local store never sees it. */
     private readonly branch?: BranchScope,
+    uploadConcurrency?: number,
   ) {
     this.lanes = remotes.map(
-      (r) => new RemoteLane(r, local.traffic, branch?.remote(r.remote) ?? r.remote),
+      (r) =>
+        new RemoteLane(r, local.traffic, branch?.remote(r.remote) ?? r.remote, uploadConcurrency),
     )
   }
 
@@ -238,6 +251,27 @@ export class LayeredCache implements CacheLayer {
    */
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
     if (this.readable.length === 0) return null
+    const answer = this.probeMany(hashes)
+    const waiting = hashes.filter((h) => !this.inflight.has(h) && !this.probing.has(h))
+    for (const h of waiting) {
+      this.probing.set(
+        h,
+        answer.then(
+          (found) => {
+            this.probing.delete(h)
+            return found === null || found.has(h)
+          },
+          () => {
+            this.probing.delete(h)
+            return true
+          },
+        ),
+      )
+    }
+    return answer
+  }
+
+  private async probeMany(hashes: readonly string[]): Promise<Set<string> | null> {
     let out: Set<string> | null = new Set()
     for (const lane of this.readable) {
       const found = await lane.hasMany(hashes)
@@ -261,6 +295,17 @@ export class LayeredCache implements CacheLayer {
     }
   }
 
+  probeFirst(started: Promise<void>): void {
+    const gate = started.then(
+      () => {},
+      () => {},
+    )
+    this.probeStarted = gate
+    void gate.then(() => {
+      if (this.probeStarted === gate) this.probeStarted = null
+    })
+  }
+
   probeBeforeUpload(hashes: Promise<readonly string[]>): void {
     for (const lane of this.lanes) lane.probeBeforeUpload(hashes)
   }
@@ -331,6 +376,11 @@ export class LayeredCache implements CacheLayer {
   private pullFromRemote(hash: string, ctx?: CacheGetContext): Promise<boolean> {
     const existing = this.inflight.get(hash)
     if (existing) return existing
+    const probed = this.probing.get(hash)
+    if (probed !== undefined)
+      return probed.then((found) => (found ? this.pullFromRemote(hash, ctx) : false))
+    if (this.probeStarted !== null)
+      return this.probeStarted.then(() => this.pullFromRemote(hash, ctx))
     const p = this.doPullFromRemote(hash, ctx)
     this.inflight.set(hash, p)
     return p
@@ -457,8 +507,10 @@ export class LayeredCache implements CacheLayer {
         return
       }
     }
-    const body = (): { body: Blob; release?: () => Promise<void> } =>
-      packed !== undefined ? { body: new Blob([packed]) } : this.local.pinArtifact(hash)
+    const body = (): Promise<{ body: Blob; release?: () => Promise<void> }> =>
+      packed !== undefined
+        ? Promise.resolve({ body: new Blob([packed]) })
+        : this.local.pinArtifact(hash)
     for (const lane of writable) lane.upload(hash, durationMs, body, this.local.uploads)
   }
 

package/src/cache/plugin-cache.ts

@@ -19,17 +19,21 @@ export const PLUGIN_ENTRY_MAX_BYTES = 1024 * 1024
 
 /** What a plugin's `ctx.cache` offers. Keys are the plugin's own names. */
 export interface PluginCache {
-  /** The bytes stored under `key`, from the first layer holding them; null when none does. */
-  get(key: string): Promise<Uint8Array | null>
+  /**
+   * The bytes stored under `key`, from the first layer holding them; null
+   * when none does. On a scoped run a remote is asked for the branch's
+   * entry, or with `scoped` false the base branch's: one request either way.
+   */
+  get(key: string, scoped?: boolean): Promise<Uint8Array | null>
   /** Store `bytes` under `key` in every layer the policy writes, where it is not already; empty bytes store nothing. */
   put(key: string, bytes: Uint8Array): Promise<void>
   /** Whether some layer holds `key`; null when no layer could answer. */
-  has(key: string): Promise<boolean | null>
+  has(key: string, scoped?: boolean): Promise<boolean | null>
   /**
    * The subset of `keys` some layer holds, in one probe per layer; null
    * when a readable remote has no batch probe: ask `get` one at a time.
    */
-  hasMany(keys: readonly string[]): Promise<Set<string> | null>
+  hasMany(keys: readonly string[], scoped?: boolean): Promise<Set<string> | null>
   /**
    * What core kept of a run under `name` (a `log` or `outputs` name its
    * `RunReport` hands `teardown`), from the first readable remote holding
@@ -88,8 +92,9 @@ async function capped(body: unknown, max = PLUGIN_ENTRY_MAX_BYTES): Promise<Uint
 /**
  * `plugin`'s view of the cache. The local store never knows a scope
  * (owner, 2026-10-17): it keeps every entry under its name's key. A scoped
- * run reads a remote under the default key, then the scope's, and writes
- * a remote only under the scope's.
+ * run writes a remote only under the scope's key, and reads one key: the
+ * scope's, or with `scoped` false the default (M, 2026-10-18: no request
+ * twice).
  */
 export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache {
   const { db, policy, scope } = host
@@ -97,9 +102,9 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
   const writers = host.remotes.filter((r) => r.write)
   const at: RemoteKey = scope === undefined ? {} : { scope }
   const atOf = (key: string, name: string): RemoteKey => (key === entryKey(plugin, name) ? {} : at)
-  const reads = (name: string): string[] => {
+  const readKey = (name: string, scoped: boolean): string => {
     const key = entryKey(plugin, name)
-    return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+    return scope === undefined || !scoped ? key : scopedKey(scope, key)
   }
   const writeKey = (name: string): string => {
     const key = entryKey(plugin, name)
@@ -143,23 +148,21 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
   }
 
   return {
-    async get(name) {
+    async get(name, scoped = true) {
       const local = entryKey(plugin, name)
       const hit = localGet(local)
       if (hit !== null) return hit
-      const keys = reads(name)
+      const key = readKey(name, scoped)
       for (const { remote } of readers) {
-        for (const key of keys) {
-          try {
-            const got = await remote.get(key, atOf(key, name))
-            if (got === null) continue
-            const bytes = await capped(got.body)
-            if (bytes === null) continue
-            if (policy.localWrite) localPut(local, bytes)
-            return bytes
-          } catch {
-            // a failing remote is a miss there
-          }
+        try {
+          const got = await remote.get(key, atOf(key, name))
+          if (got === null) continue
+          const bytes = await capped(got.body)
+          if (bytes === null) continue
+          if (policy.localWrite) localPut(local, bytes)
+          return bytes
+        } catch {
+          // a failing remote is a miss there
         }
       }
       return null
@@ -178,26 +181,24 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
       }
     },
 
-    async has(name) {
+    async has(name, scoped = true) {
       if (localHas([entryKey(plugin, name)]).size > 0) return true
-      const keys = reads(name)
+      const key = readKey(name, scoped)
       let answered = policy.localRead
       for (const { remote } of readers) {
-        for (const key of keys) {
-          try {
-            if (await remote.has(key, atOf(key, name))) return true
-            answered = true
-          } catch {
-            // no answer from this remote
-          }
+        try {
+          if (await remote.has(key, atOf(key, name))) return true
+          answered = true
+        } catch {
+          // no answer from this remote
         }
       }
       return answered ? false : null
     },
 
-    async hasMany(names) {
+    async hasMany(names, scoped = true) {
       const byKey = new Map<string, string>()
-      for (const name of names) for (const key of reads(name)) byKey.set(key, name)
+      for (const name of names) byKey.set(readKey(name, scoped), name)
       const keys = [...byKey.keys()]
       const found = new Set<string>()
       for (const key of localHas(names.map((n) => entryKey(plugin, n)))) found.add(byKey.get(key)!)

package/src/cache/remote-lane.ts

@@ -4,6 +4,7 @@
 // class with the endpoint named. The order across remotes, the local store
 // and provenance are `LayeredCache`'s; nothing here knows another remote.
 
+import { machineParallelism } from '../util/index.js'
 import type { RemoteKeyTraffic, RemoteTraffic } from './cache.js'
 import type { RemoteCacheLayer } from './layered-cache.js'
 
@@ -20,11 +21,13 @@ export interface ResolvedRemote {
 }
 
 /**
- * Cap on concurrent background PUTs per remote. Keeps a burst of cache
- * misses from opening one socket per task; excess uploads queue and drain
- * FIFO.
+ * Requests at once to a remote, by default: pnpm's network concurrency
+ * (Bun's is a fixed 64). A request waits on the network, not a core, so
+ * the cap follows cores only past 21 of them.
  */
-const UPLOAD_CONCURRENCY = 4
+export function networkConcurrency(): number {
+  return Math.min(96, Math.max(machineParallelism() * 3, 64))
+}
 
 /** The seam call a failure happened in, as the warning names it. */
 export type RemoteOp = 'probe' | 'download' | 'upload'
@@ -135,6 +138,8 @@ export class RemoteLane {
     private readonly traffic: RemoteTraffic,
     /** The wire as this run asks it: a branch scope's view of `resolved.remote`. */
     remote: RemoteCacheLayer = resolved.remote,
+    /** Background PUTs at once; excess uploads queue and drain FIFO. */
+    private readonly uploadConcurrency: number = networkConcurrency(),
   ) {
     this.resolved = resolved
     this.remote = remote
@@ -255,7 +260,7 @@ export class RemoteLane {
   upload(
     hash: string,
     durationMs: number,
-    body: () => { body: Blob; release?: () => Promise<void> },
+    body: () => Promise<{ body: Blob; release?: () => Promise<void> }>,
     tally: { count: number; bytes: number; ms: number; failed: number },
   ): void {
     const key = this.trafficOf(hash)
@@ -268,7 +273,7 @@ export class RemoteLane {
         if (!this.read && (await this.holds(hash))) return
         if (this.stopped) return
         const start = performance.now()
-        const got = body()
+        const got = await body()
         release = got.release
         await this.remote.put(hash, got.body, { durationMs })
         tally.count++
@@ -369,7 +374,7 @@ export class RemoteLane {
   }
 
   private pump(): void {
-    while (this.activeUploads < UPLOAD_CONCURRENCY && this.uploadQueue.length > 0) {
+    while (this.activeUploads < this.uploadConcurrency && this.uploadQueue.length > 0) {
       const job = this.uploadQueue.shift()!
       this.activeUploads++
       // Jobs never reject (each wraps its PUT in the never-fail guard).

package/src/cache/tar-stream.ts

@@ -122,14 +122,19 @@ class Source {
   constructor(private readonly reader: AsyncIterator<Uint8Array>) {}
 
   private async fill(): Promise<boolean> {
-    if (this.done) return false
-    const { done, value } = await this.reader.next()
-    if (done === true || value === undefined) {
-      this.done = true
-      return false
+    // An empty chunk is skipped, never reported as data: the callers read
+    // `chunks[0]` after a true (the tar a tree packs back yields them).
+    for (;;) {
+      if (this.done) return false
+      const { done, value } = await this.reader.next()
+      if (done === true || value === undefined) {
+        this.done = true
+        return false
+      }
+      if (value.byteLength === 0) continue
+      this.chunks.push(value)
+      return true
     }
-    if (value.byteLength > 0) this.chunks.push(value)
-    return true
   }
 
   /** Exactly `n` bytes, or null at a clean end (nothing buffered), or a TarFormatError mid-entry. */

package/src/cli/format.ts

@@ -1,4 +1,3 @@
-// `formatBytes` moved to util/size.ts beside the parsers (item 658): a run
-// names what the workspace's `cacheRetention` evicted, and the orchestrator
+// `formatBytes` lives in util/size.ts beside the parsers: the orchestrator
 // may not import the CLI.
 export { formatBytes } from '../util/index.js'

package/src/cli/help.ts

@@ -163,6 +163,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  .vx/cache, entries in ~/.vx/<id>/cache.',
     '      --cache-download <mode>     all (default) | toplevel | none:',
     '                                  where remote outputs land.',
+    '      --cache-concurrency-download <n>',
+    '                                  Remote downloads at once.',
+    '      --cache-concurrency-upload <n>',
+    '                                  Uploads at once, per remote.',
+    '      --cache-concurrency-restore <n>',
+    '                                  Local hits restoring at once.',
     '      --retries <n>               Up to <n> more runs of a failed task, for',
     '                                  tasks without their own exec.retries. Not',
     '                                  folded into cache keys.',

package/src/cli/info.ts

@@ -100,9 +100,6 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
     ...(Object.values(f.settings).some((s) => s.source !== 'default')
       ? ([['settings', describeSettings(f.settings)]] as [string, string][])
       : []),
-    ...(f.cacheRetention !== null
-      ? ([['cache retention', describeRetention(f.cacheRetention)]] as [string, string][])
-      : []),
     // Only when there is something to say.
     ...(f.orphans.artifacts > 0
       ? ([
@@ -128,14 +125,9 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
   return ui.report('vx info', rows).lines(colors).join('\n')
 }
 
-/** `812 (1.2 GB)`, or against `cacheRetention.maxSize`: `812 (1.2 GB of 10 GB, 12%)`. */
+/** `812 (1.2 GB)`. */
 function describeEntries(f: InfoFacts): string {
-  const max = f.cacheRetention?.maxBytes
-  const size =
-    max === undefined
-      ? formatBytes(f.cacheBytes)
-      : `${formatBytes(f.cacheBytes)} of ${formatBytes(max)}, ${Math.round((f.cacheBytes / max) * 100)}%`
-  return `${f.cacheEntries} (${size})`
+  return `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`
 }
 
 /**
@@ -152,15 +144,6 @@ function describeSettings(settings: InfoFacts['settings']): string {
     .join(', ')
 }
 
-/** What a run's end evicts: `entries unused for 30d, and the oldest entries past 10G`. */
-function describeRetention(r: NonNullable<InfoFacts['cacheRetention']>): string {
-  const parts = [
-    ...(r.olderThan !== undefined ? [`entries unused for ${r.olderThan}`] : []),
-    ...(r.maxSize !== undefined ? [`the oldest entries past ${r.maxSize}`] : []),
-  ]
-  return `each run evicts ${parts.join(', and ')}`
-}
-
 /** A path under the home directory as `~/…`: shorter, and no user name in a pasted report. */
 function tildePath(p: string): string {
   const home = os.homedir()

package/src/cli/plugin-commands.ts

@@ -144,7 +144,7 @@ async function verbCache(
   ])
   const scope = resolveCacheScope(
     ws.workspaceRoot,
-    ws.branch.scope,
+    ws.branch.trusted === true ? null : ws.branch.scope,
     ws.plugins.some((p) => p.cache !== undefined),
     configuredBaseBranch(ws.workspaceConfig),
   )

package/src/cli/run.ts

@@ -109,6 +109,9 @@ const SETTING_OPTIONS = [
   ['run.retries', 'retries'],
   ['run.outputLogs', 'outputLogs'],
   ['cache.download', 'download'],
+  ['cache.concurrency.download', 'downloadConcurrency'],
+  ['cache.concurrency.upload', 'uploadConcurrency'],
+  ['cache.concurrency.restore', 'restoreConcurrency'],
 ] as const satisfies readonly (readonly [string, keyof RunOptions])[]
 
 /** `verb` is the one being parsed for: `vx watch` reads `vx run`'s flags, and

package/src/cli/upgrade.ts

@@ -21,6 +21,7 @@ import { access, chmod, chown, link, mkdtemp, rename, rm, stat } from 'node:fs/p
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError, sayNotice, ui } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
 import { VERSION } from '../version.js'
 
 const REGISTRY = 'https://registry.npmjs.org'
@@ -596,11 +597,11 @@ export async function upgradeManaged(
   version: string,
   current = VERSION,
   step = '',
-): Promise<void> {
+): Promise<boolean> {
   const plugins = install.plugins ?? []
   if (version === current && plugins.every((p) => installedVersion(install.cwd, p) === version)) {
     ui.print('out', ui.status('info', 'vx upgrade', `${step}already at ${current}`))
-    return
+    return false
   }
   const argv = upgradeArgv(install, version)
   // PATH as it is now: `Bun.which` alone reads the one the process started with.
@@ -636,6 +637,7 @@ export async function upgradeManaged(
       }`,
     )
   }
+  return true
 }
 
 /**
@@ -648,7 +650,7 @@ async function upgradeBinary(
   current = VERSION,
   step = '',
   key: SigningKey = NPM_SIGNING_KEY,
-): Promise<void> {
+): Promise<boolean> {
   const pkg = platformPackage()
   let installed: string | undefined
   const replaced = await replaceBinary(
@@ -679,6 +681,7 @@ async function upgradeBinary(
       ? ui.status('ok', 'vx upgrade', `${step}installed ${installed}`)
       : ui.status('info', 'vx upgrade', `${step}already at ${current}`),
   )
+  return replaced
 }
 
 /** The version `bin --version` answers, without the hand-off note a handed-off run adds. */
@@ -738,9 +741,9 @@ export async function upgradeOnlyGlobal(
 }
 
 /** `run`, its refusal naming `what` after the verb: a run that moves two installs says which failed. */
-async function named(what: string, run: () => Promise<void>): Promise<void> {
+async function named<T>(what: string, run: () => Promise<T>): Promise<T> {
   try {
-    await run()
+    return await run()
   } catch (err) {
     if (!(err instanceof UserError)) throw err
     throw new UserError(err.message.replace(/^vx upgrade: /, `vx upgrade: ${what}: `), err.code)
@@ -787,19 +790,46 @@ export async function upgradeCmd(argv: readonly string[]): Promise<number> {
   const from = handedOffFrom
   if (from !== undefined) {
     const version = await targetVersion(tag)
-    await named('project vx', () =>
+    const moved = await named('project vx', () =>
       install === null
         ? upgradeBinary(dest, version, VERSION, 'project ')
         : upgradeManaged(install, version, VERSION, 'project '),
     )
     await upgradeGlobal(from, version)
+    if (moved) await relock(newVx(install, dest))
     return 0
   }
-  if (install !== null) await upgradeManaged(install, await targetVersion(tag))
-  else await upgradeBinary(dest, versionSpec(tag))
+  const moved =
+    install !== null
+      ? await upgradeManaged(install, await targetVersion(tag))
+      : await upgradeBinary(dest, versionSpec(tag))
+  if (moved) await relock(newVx(install, dest))
   return 0
 }
 
+/**
+ * The vx an upgrade just installed: the replaced binary, or the project's
+ * `node_modules/.bin/vx` (a manager's store path names the old version).
+ */
+const newVx = (install: ManagedInstall | null, dest: string): string =>
+  install === null ? dest : path.join(install.cwd, 'node_modules', '.bin', 'vx')
+
+/**
+ * Lock the workspace with the vx just installed at `bin` (M, 2026-10-18):
+ * a release may record the lock differently. `-g` never re-locks. A lock
+ * that fails leaves the upgrade done and says what to run.
+ */
+export async function relock(bin: string, cwd = process.cwd()): Promise<void> {
+  const root = await findWorkspaceRoot(cwd).catch(() => null)
+  if (root === null) return
+  const proc = Bun.spawnSync({
+    cmd: [bin, 'lock'],
+    cwd: root,
+    stdio: ['inherit', 'inherit', 'inherit'],
+  })
+  if (proc.exitCode !== 0) sayNotice('warn', 'vx upgrade', 'vx lock failed: run vx lock')
+}
+
 /**
  * `bin --version` when it answers as vx within `timeoutMs`, else null. The
  * answer decides whether a replaced binary is rolled back, so it is