@vzn/vx 0.0.645 → 0.0.646

package/src/cache/output-index.ts

@@ -18,11 +18,11 @@ const FILE_PREFIX_MTIME = -2
 import type { Database } from 'bun:sqlite'
 import { inHashes, lazyStatement } from './schema.js'
 import { modeMatches } from './umask.js'
-import { lstatSync, readlinkSync, statSync } from 'node:fs'
-import { lstat, readdir } from 'node:fs/promises'
+import { lstatSync, readdirSync, readlinkSync, statSync } from 'node:fs'
 import path from 'node:path'
 import {
   OUTPUT_DIRS_CAP,
+  OUTPUT_DIRS_OVER_CAP,
   OUTPUT_DIRS_RACY_MS,
   type OutputDirRow,
   isIndexFull,
@@ -262,8 +262,8 @@ export class OutputIndex {
    * process may have written into them: `holds` is asked with the files
    * the walk saw, and a tree it refuses records nothing (item 1087).
    * Symlinked directories are not descended (the output walk refuses them
-   * too). Over `OUTPUT_DIRS_CAP` directories, or on any error, the rows
-   * are cleared and the next hit keeps the walk.
+   * too). Over `OUTPUT_DIRS_CAP` directories the one row left says so; on
+   * any error the rows are cleared. Either way the next hit keeps the walk.
    */
   async recordOutputDirs(
     hash: string,
@@ -273,11 +273,16 @@ export class OutputIndex {
   ): Promise<void> {
     const rows: Array<[string, number]> = []
     const files: string[] = []
-    const walk = async (rel: string, isPrefix = false): Promise<boolean> => {
+    let overCap = false
+    // Synchronous, like the stats of `isOutputsCurrent`: an async lstat and
+    // readdir per directory are two thread-pool round trips, and a
+    // root-anchored glob's snapshot of solid's 47 directories took 4 ms of
+    // the run's end that way (2026-10-22).
+    const walk = (rel: string, isPrefix = false): boolean => {
       const abs = path.join(projectDir, rel)
       let st
       try {
-        st = await lstat(abs)
+        st = lstatSync(abs)
       } catch {
         // A declared prefix the task never produced (`build/**` beside
         // `dist/**`, medusa's `.medusa/**`) is recorded ABSENT: the check
@@ -299,29 +304,38 @@ export class OutputIndex {
         return true
       }
       rows.push([rel, st.mtimeMs])
-      if (rows.length > OUTPUT_DIRS_CAP) return false
+      if (rows.length > OUTPUT_DIRS_CAP) {
+        overCap = true
+        return false
+      }
       let entries
       try {
-        entries = await readdir(abs, { withFileTypes: true })
+        entries = readdirSync(abs, { withFileTypes: true })
       } catch {
         return false
       }
       for (const e of entries) {
+        // The project itself is the prefix `''` of a root-anchored glob.
+        const child = rel === '' ? e.name : `${rel}/${e.name}`
         if (e.isDirectory() && !e.isSymbolicLink()) {
-          if (!(await walk(`${rel}/${e.name}`))) return false
+          if (!walk(child)) return false
         } else {
-          files.push(`${rel}/${e.name}`)
+          files.push(child)
         }
       }
       return true
     }
     let ok = true
     for (const prefix of prefixes) {
-      if (!(await walk(prefix, true))) {
+      if (!walk(prefix, true)) {
         ok = false
         break
       }
     }
+    if (overCap) {
+      this.pendingDirs.set(hash, [[prefixes[0]!, OUTPUT_DIRS_OVER_CAP]])
+      return
+    }
     // All or nothing: a racy directory dropped alone would leave its
     // parent trusted while an addition inside it bumps only the dropped one.
     const now = Date.now()

package/src/cache/remote-lane.ts

@@ -228,9 +228,15 @@ export class RemoteLane {
     return out
   }
 
-  /** The artifact's body, or null on a miss, a known absence, a failure or a malformed answer. */
-  async get(hash: string): Promise<{ body: Blob | Response; durationMs?: number } | null> {
-    if (this.absent.has(hash)) return null
+  /**
+   * The artifact's body, or null on a miss, a known absence (unless
+   * `fresh`: saved since the probe), a failure or a malformed answer.
+   */
+  async get(
+    hash: string,
+    fresh = false,
+  ): Promise<{ body: Blob | Response; durationMs?: number } | null> {
+    if (!fresh && this.absent.has(hash)) return null
     let result: unknown
     try {
       result = await this.remote.get(hash)
@@ -253,7 +259,10 @@ export class RemoteLane {
       )
       return null
     }
-    return result as { body: Blob | Response; durationMs?: number }
+    // It holds the key: a save of it after this restore uploads nothing.
+    const got = result as { body: Blob | Response; durationMs?: number }
+    this.held.set(hash, got.durationMs === undefined ? {} : { durationMs: got.durationMs })
+    return got
   }
 
   /**

package/src/cache/run-history.ts

@@ -13,11 +13,12 @@ const INSERT_RUNS = `
         started_at, ended_at,
         run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
         cache_hit, attempts, cached,
-        blocked_by, timed_out, sandbox_violations, not_ready, restored, remote_error
+        blocked_by, timed_out, sandbox_violations, not_ready, restored, remote_error,
+        peak_cores, avg_rss_bytes, placement, placement_cores, placement_memory, keyless_by
       )
       VALUES `
-/** One `runs` row's placeholders: the 23 columns `bindRun` fills. */
-const RUN_TUPLE = `(${Array(23).fill('?').join(', ')})`
+/** One `runs` row's placeholders: the 29 columns `bindRun` fills. */
+const RUN_TUPLE = `(${Array(29).fill('?').join(', ')})`
 
 /** An INSERT of `n` `runs` rows. */
 function insertRunsSql(n: number): string {
@@ -25,11 +26,11 @@ function insertRunsSql(n: number): string {
 }
 
 /**
- * Rows per INSERT: 40 × 23 variables stays under 999, the oldest default
+ * Rows per INSERT: 34 × 29 variables stays under 999, the oldest default
  * ceiling. A statement per row was 8.7 ms of 1,000 rows, 40 at a time 6.4
  * (2026-10-03).
  */
-const RUNS_PER_INSERT = 40
+const RUNS_PER_INSERT = 34
 
 /** Rows per `task_durations` INSERT: 6 variables each, under 999. */
 const DURATIONS_PER_INSERT = 160
@@ -236,7 +237,7 @@ export class RunHistory {
   }
 }
 
-/** Bind a RunRecord to one `RUN_TUPLE`'s 23 positional parameters. */
+/** Bind a RunRecord to one `RUN_TUPLE`'s 29 positional parameters. */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
@@ -267,6 +268,12 @@ function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBi
     run.notReady ?? null,
     run.restored === undefined ? null : run.restored ? 1 : 0,
     run.remoteError ?? null,
+    run.peakCores ?? null,
+    run.avgRssBytes ?? null,
+    run.placement ?? null,
+    run.placementCores ?? null,
+    run.placementMemoryBytes ?? null,
+    run.keylessBy ?? null,
   ]
 }
 

package/src/cache/schema.ts

@@ -101,7 +101,18 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       restored            INTEGER,
       -- v40: each remote read or write of the key that failed, as
       -- 'upload: <message>', '; '-joined; NULL when none did.
-      remote_error        TEXT
+      remote_error        TEXT,
+      -- v43: the most cores one sampling interval burned and the mean
+      -- resident memory over the looks; NULL when nothing sampled.
+      peak_cores          REAL,
+      avg_rss_bytes       INTEGER,
+      -- v44: where an executor ran it (ExecuteResult.where) and that
+      -- machine's cores and memory; NULL = here.
+      placement           TEXT,
+      placement_cores     INTEGER,
+      placement_memory    INTEGER,
+      -- v46: the task with no inputs its key folded (TaskOutcome.keylessBy).
+      keyless_by          TEXT
     );
     -- Two whole-table indexes only, and both APPEND: every row of a run carries the
     -- same run_id and a started_at newer than everything before it, so
@@ -280,7 +291,13 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       source      TEXT NOT NULL,
       sha         TEXT,
       duration_ms INTEGER NOT NULL,
-      recorded_at INTEGER NOT NULL
+      recorded_at INTEGER NOT NULL,
+      -- v45: a 'remote' row's measured need (TaskResources); NULL on the
+      -- rest, whose need the run history holds.
+      cpu_parallelism        REAL,
+      peak_rss_bytes         INTEGER,
+      saturated_cores        INTEGER,
+      saturated_memory_bytes INTEGER
     );
     CREATE INDEX IF NOT EXISTS ${store}.task_durations_task
       ON task_durations(project, task, source, id);

package/src/cli/core-alias.ts

@@ -14,12 +14,15 @@
  * so a verb that never loads a plugin never loads the façade. The
  * source form (`bun src/bin.ts`) resolves the specifier to the same file
  * anyway; the alias makes that a guarantee rather than a layout fact.
+ * The loader is synchronous: the workspace config's bytecode bundle
+ * (workspace/config-bytecode.ts) is CommonJS, and `require` refuses a
+ * module whose loader is async.
  */
-export function registerCoreAlias(load: () => Promise<Record<string, unknown>>): void {
+export function registerCoreAlias(load: () => Record<string, unknown>): void {
   Bun.plugin({
     name: 'vx-core-alias',
     setup(build) {
-      build.module('@vzn/vx', async () => ({ exports: await load(), loader: 'object' }))
+      build.module('@vzn/vx', () => ({ exports: load(), loader: 'object' }))
     },
   })
 }

package/src/cli/help.ts

@@ -199,12 +199,6 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  depends on none of them; a plain `vx run` never requires a plugin.',
     '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
     '',
-    'Turbo and Nx spellings (for run):',
-    '  What turbo run / nx run-many / nx affected take works here, or is refused',
-    '  naming the vx spelling: -t build,test, -p app, --exclude docs, --parallel 4,',
-    '  and --base main, --dry-run, --skip-nx-cache. `vx build` names `vx run build`.',
-    '  Every flag: https://vznjs.github.io/vx/cli/#turbo-and-nx-flags',
-    '',
     'Argument forwarding (for run):',
     "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
     '  command. The forwarded args are folded into the cache key.',
@@ -356,6 +350,10 @@ export function flagHint(verb: string, arg: string): string {
   // `--json` is gh's and Nx's spelling; a verb with `--format` reads it
   // there, and no edit budget reaches `--format json` from `--json`.
   if (name === '--json' && flags.includes('--format')) return ' (did you mean --format json?)'
+  // `vx run` prints no JSON of its own, and edit distance reached `--force`
+  // from `--format`: a run with its cache reads turned off.
+  if ((name === '--format' || name === '--json') && flags.includes('--dry'))
+    return ' (the run as JSON is `vx last --format json` after it; the plan is --dry=json)'
   // A flag cut short at a word (`--dry` for prune's `--dry-run`, which
   // `vx run` spells `--dry`) is too many edits away for either budget.
   const cut = flags.filter((f) => f.startsWith(`${name}-`))

package/src/cli/index.ts

@@ -4,7 +4,6 @@
 import { VERSION } from '../version.js'
 import { checkSettingsEnv } from '../settings.js'
 import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
-import { FOREIGN_VERBS } from './foreign-flags.js'
 import {
   errorDocument,
   hideEnvFromTasks,
@@ -99,11 +98,6 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         // for the whole reference: it printed 145 lines and no hint.
         const resolved = await (await plugins()).resolvePluginCommand(verb)
         const unknown = resolved === null || 'declaredVerbs' in resolved
-        const pointer = FOREIGN_VERBS[verb]
-        if (unknown && pointer !== undefined) {
-          sayNotice('info', 'vx', pointer)
-          return 1
-        }
         if (unknown && verb.startsWith('-')) {
           sayNotice(
             'error',
@@ -217,12 +211,6 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: .vx/workspace failed to load: ${resolved.loadError})`
           : ''
-      // Another tool's verb: the pointer, but only after the plugins had
-      // their chance — a workspace that declares a plugin verb of that name keeps it.
-      const moved = FOREIGN_VERBS[command]
-      if (moved !== undefined) {
-        return unknown(`${moved}${loadNote}\n`, undefined, 'info')
-      }
       // A task typed where the verb goes (`turbo build`, `nx build app`),
       // `turbo dev` included: a repo's own `dev` task beats the no-service note.
       const declaredVerbs =

package/src/cli/init.ts

@@ -26,7 +26,6 @@ import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from
 import {
   findWorkspaceRoot,
   PROJECT_CONFIG_FILENAMES,
-  vxInvocation,
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
@@ -137,10 +136,11 @@ export function initInstalls(
   pkgRoot: string | null,
   globalAt: string | undefined,
   execPath = process.execPath,
+  plugins: readonly string[] = [],
 ): { argv: string[]; cwd: string | null }[] {
   const out: { argv: string[]; cwd: string | null }[] = []
   if (globalAt !== version) {
-    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'npm'
+    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'bun'
     const manager = runner as ManagedInstall['manager']
     out.push({ argv: upgradeArgv({ manager, scope: 'global', cwd: '' }, version), cwd: null })
   }
@@ -150,6 +150,7 @@ export function initInstalls(
       scope: 'project',
       cwd: pkgRoot,
       field: 'devDependencies',
+      plugins: [...plugins],
     }
     out.push({ argv: upgradeArgv(install, version), cwd: pkgRoot })
   }
@@ -172,7 +173,11 @@ function globalVersion(): string | undefined {
  * Run `initInstalls`, in order. A source checkout (0.0.0, which npm never
  * had) installs nothing: the release would replace the code under test.
  */
-async function install(pkgRoot: string | null, dry: boolean): Promise<string[]> {
+async function install(
+  pkgRoot: string | null,
+  dry: boolean,
+  plugins: readonly string[] = [],
+): Promise<string[]> {
   if (VERSION === '0.0.0') return []
   const version = await targetVersion(undefined, 'vx init')
   const steps = initInstalls(
@@ -180,6 +185,8 @@ async function install(pkgRoot: string | null, dry: boolean): Promise<string[]>
     process.env['npm_config_user_agent'],
     pkgRoot,
     globalVersion(),
+    process.execPath,
+    plugins,
   )
   if (dry) return steps.map((s) => s.argv.join(' '))
   for (const s of steps) {
@@ -235,8 +242,26 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
   return 0
 }
 
-const WORKSPACE =
-  "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
+/**
+ * The `@vzn/vx-lockfile` plugin the lockfile at `pkgRoot` calls for: without
+ * it a JS workspace has no project edges, and the first `^build` a user
+ * writes is refused at `vx lock`.
+ */
+function lockfilePlugin(pkgRoot: string | null): 'pnpm' | 'bun' | 'yarn' | 'npm' | null {
+  if (pkgRoot === null) return null
+  const has = (f: string): boolean => existsSync(path.join(pkgRoot, f))
+  if (has('pnpm-lock.yaml')) return 'pnpm'
+  if (has('bun.lock') || has('bun.lockb')) return 'bun'
+  if (has('yarn.lock')) return 'yarn'
+  if (has('package-lock.json') || has('npm-shrinkwrap.json')) return 'npm'
+  return null
+}
+
+function workspaceSource(plugin: string | null): string {
+  if (plugin === null)
+    return "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
+  return `import { defineWorkspace } from '@vzn/vx'\nimport { ${plugin} } from '@vzn/vx-lockfile'\n\nexport default defineWorkspace({ plugins: [${plugin}()] })\n`
+}
 const PROJECT =
   "import { defineProject } from '@vzn/vx'\n\nexport default defineProject({ tasks: {} })\n"
 
@@ -257,14 +282,23 @@ async function starter(
       `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no turbo.json or nx.json here`,
     )
   }
-  const installs = args.json === true || args.dry ? await install(pkgRoot, true) : []
+  // A source checkout installs nothing, so it declares the plugin only where one is.
+  const found = lockfilePlugin(pkgRoot)
+  const plugin =
+    found !== null &&
+    (VERSION !== '0.0.0' ||
+      existsSync(path.join(pkgRoot!, 'node_modules', '@vzn', 'vx-lockfile', 'package.json')))
+      ? found
+      : null
+  const plugins = plugin === null ? [] : ['@vzn/vx-lockfile']
+  const installs = args.json === true || args.dry ? await install(pkgRoot, true, plugins) : []
   const ext = args.mjs ? 'mjs' : 'ts'
   const config = `vx.config.${ext}`
   const files: { path: string; contents: string }[] = []
   const kept: string[] = []
   const replaced: string[] = []
   for (const [names, name, contents] of [
-    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, WORKSPACE],
+    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, workspaceSource(plugin)],
     [PROJECT_CONFIG_FILENAMES, config, PROJECT],
   ] as const) {
     const existing = names.find((n) => existsSync(path.join(root, n)))
@@ -281,8 +315,7 @@ async function starter(
   ] as const) {
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
-  const vx = VERSION === '0.0.0' ? vxInvocation(process.env['npm_config_user_agent'], false) : 'vx'
-  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then ${vx} lock && ${vx} run <task>`
+  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then vx lock && vx run <task>`
   if (args.json === true) {
     process.stdout.write(
       `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
@@ -300,7 +333,7 @@ async function starter(
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
-  const ran = await install(pkgRoot, false)
+  const ran = await install(pkgRoot, false, plugins)
   if (ran.length > 0) rows.push(['installed', ...ran])
   for (const f of files) await Bun.write(path.join(root, f.path), f.contents)
   for (const f of replaced) await unlink(path.join(root, f))

package/src/cli/last.ts

@@ -365,10 +365,12 @@ export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
     ? [...hits].sort((a, b) => b.durationMs - a.durationMs).slice(0, HITS_SHOWN)
     : hits
   const ordered = [...failed, ...rest, ...shownHits]
-  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}`.length), 4)
+  const at = (t: (typeof ordered)[number]): string =>
+    t.placement !== null ? `@${t.placement}` : ''
+  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}${at(t)}`.length), 4)
   const lines = ['']
   for (const t of ordered) {
-    const id = `${t.project}#${t.task}`
+    const id = `${t.project}#${t.task}${at(t)}`
     // The terminal summary's own word for a task that runs every time
     // by design; a reader must not take its row for a miss.
     // A failure's row reads as the frame did — `failed (exit 137)` —

package/src/cli/plugin-commands.ts

@@ -9,9 +9,16 @@
 
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
-import type { BranchFacts, VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
+import type {
+  BranchFacts,
+  VxPlugin,
+  PluginCommand,
+  CommandContext,
+  CacheFacts,
+  TaskArtifacts,
+} from '../orchestrator/index.js'
 import { configuredBaseBranch, findWorkspaceRoot } from '../workspace/index.js'
-import { machineParallelism, maskedLine } from '../util/index.js'
+import { machineParallelism, maskedLine, SecretBroker } from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
@@ -111,6 +118,8 @@ export async function resolvePluginCommand(
           : [process.execPath, Bun.main],
         warn,
         cache: lazyCache(() => verbCache(ws, plugin.name)),
+        artifacts: lazyArtifacts(() => verbArtifacts(ws)),
+        artifactsFor: (facts) => lazyArtifacts(() => verbArtifacts(ws, facts)),
       },
     }
   }
@@ -138,7 +147,7 @@ async function verbCache(
   ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
   plugin: string,
 ): Promise<PluginCache> {
-  const [{ Cache, pluginCache }, { cacheRefs, resolveCache, resolveCacheScope }] =
+  const [{ Cache, pluginCache }, { cacheRefs, openRemotes, resolveCache, resolveCacheScope }] =
     await Promise.all([import('../cache/index.js'), import('../orchestrator/index.js')])
   const scope = resolveCacheScope(
     ws.workspaceRoot,
@@ -165,9 +174,93 @@ async function verbCache(
     policy: VERB_POLICY,
     remotes,
   })
+  await openVerbRemotes(remotes, openRemotes)
   return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
 }
 
+/**
+ * The verb's `ctx.artifacts`: the workspace's cache as a run opens it, its
+ * policy and scope, a laptop writing no remote unless the policy names it.
+ * With `facts` (`ctx.artifactsFor`), under another run's refs and lent access.
+ */
+async function verbArtifacts(
+  ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
+  facts?: () => CacheFacts | undefined,
+): Promise<TaskArtifacts> {
+  const [
+    { Cache, FULL_CACHE_POLICY },
+    {
+      cacheRefs,
+      namesRemote,
+      openRemotes,
+      resolveCache,
+      resolveCacheScope,
+      taskArtifacts,
+      workspaceCachePolicy,
+    },
+    { onCI },
+  ] = await Promise.all([
+    import('../cache/index.js'),
+    import('../orchestrator/index.js'),
+    import('./run.js'),
+  ])
+  const asked = workspaceCachePolicy(ws.workspaceConfig) ?? FULL_CACHE_POLICY
+  const policy: CachePolicy =
+    onCI(process.env['CI']) || namesRemote(ws.workspaceConfig?.cache?.policy)
+      ? asked
+      : { ...asked, remoteWrite: false }
+  const scope = resolveCacheScope(
+    ws.workspaceRoot,
+    ws.branch.trusted === true ? null : ws.branch.scope,
+    ws.plugins.some((p) => p.cache !== undefined),
+    configuredBaseBranch(ws.workspaceConfig),
+  )
+  const localCache = new Cache(
+    ws.cacheDir,
+    { read: policy.localRead, write: policy.localWrite },
+    ws.workspaceRoot,
+    undefined,
+    'open',
+    await ws.storeRoot,
+  )
+  const remotes: ResolvedRemote[] = []
+  const cache = await resolveCache(ws.plugins, {
+    workspaceRoot: ws.workspaceRoot,
+    cacheDir: ws.cacheDir,
+    warn,
+    scope,
+    refs: facts?.()?.refs ?? cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
+    localCache,
+    policy,
+    remotes,
+    ...(facts === undefined ? {} : { lentBy: () => facts()?.lent }),
+  })
+  await openVerbRemotes(remotes, openRemotes)
+  return taskArtifacts(cache, ws.workspaceRoot)
+}
+
+/**
+ * Each remote's `open`, as a run's: a remote that takes its token there
+ * (turboCache's OIDC exchange, a lent token) had none, so an agent's
+ * uploads went nowhere and its run could not restore them.
+ */
+async function openVerbRemotes(
+  remotes: readonly ResolvedRemote[],
+  open: (typeof import('../orchestrator/index.js'))['openRemotes'],
+): Promise<void> {
+  const ci = (await import('./run.js')).onCI(process.env['CI'])
+  await open(remotes, ci, new SecretBroker(ci, warn))
+}
+
+function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
+  let opened: Promise<TaskArtifacts> | undefined
+  const artifacts = (): Promise<TaskArtifacts> => (opened ??= open())
+  return {
+    save: async (key, task, run) => (await artifacts()).save(key, task, run),
+    restore: async (key, task) => (await artifacts()).restore(key, task),
+  }
+}
+
 function lazyCache(open: () => Promise<PluginCache>): PluginCache {
   let opened: Promise<PluginCache> | undefined
   const cache = (): Promise<PluginCache> => (opened ??= open())

package/src/cli/plugin-templates.ts

@@ -16,7 +16,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   commands: {
     plugin:
       "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
-    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
+    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: { save: async () => {}, restore: async () => null },\n  artifactsFor: () => ({ save: async () => {}, restore: async () => null }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
   },
   executor: {
     plugin:

package/src/cli/run.ts

@@ -1,6 +1,5 @@
 import { isatty } from 'node:tty'
 import { findWorkspaceRoot } from '../workspace/index.js'
-import { translateForeign } from './foreign-flags.js'
 import { flagHint, refuse, seeHelp } from './help.js'
 import {
   planRun,
@@ -116,7 +115,7 @@ const SETTING_OPTIONS = [
 
 /** `verb` is the one being parsed for: `vx watch` reads `vx run`'s flags, and
  * its flag hints named `vx run` (M-58). The caller appends the help pointer. */
-export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' = 'run'): RunArgs {
+export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'run'): RunArgs {
   const out: RunArgs = {
     tasks: [],
     filters: [],
@@ -132,10 +131,6 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     affected: undefined,
   }
 
-  // A Turbo or Nx spelling becomes vx's, or a refusal naming vx's.
-  const translated = translateForeign(rawArgs)
-  if ('error' in translated) return { ...out, error: translated.error }
-  const args = translated
   const sepIdx = args.indexOf('--')
   const before = sepIdx === -1 ? args : args.slice(0, sepIdx)
   out.forwardArgs = sepIdx === -1 ? [] : args.slice(sepIdx + 1)
@@ -663,6 +658,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 }
 
 /** CI=0 and CI=false are "not CI": several vendors set CI=true. */
-function onCI(v: string | undefined): boolean {
+export function onCI(v: string | undefined): boolean {
   return v !== undefined && v !== '' && v !== '0' && v !== 'false'
 }

package/src/cli/select.ts

@@ -4,6 +4,7 @@
 // here goes through the staged load, so the answer is the run's.
 
 import path from 'node:path'
+import { settingEnv } from '../settings.js'
 import fs from 'node:fs'
 import {
   affectedChanges,
@@ -244,12 +245,13 @@ function refusalOf(err: unknown): Refusal {
 
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
- * projects and their dependents. An empty base is a plugin's (`setBranch`:
- * a pull request's base commit), else the merge base with `baseBranch`.
+ * projects and their dependents. An empty base is `VX_AFFECTED_BASE`'s,
+ * else a plugin's (`setBranch`: a pull request's base commit), else the
+ * merge base with `baseBranch`.
  */
 export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
-  let base = affected
+  let base = affected || ((settingEnv('affectedBase') as string | undefined) ?? '')
   if (base === '') {
     const ws = await loadCliWorkspace(root)
     try {