@vzn/vx-migrate 0.0.644 → 0.0.646

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -10,10 +10,10 @@ Everything for adopting [`@vzn/vx`](https://vznjs.github.io/vx/) from Turborepo,
 - **`turboCache()`** and **`nxCache()`** — keep the remote cache you have: any server speaking Turbo's `/v8/artifacts` API (Vercel's hosted cache included) or Nx's self-hosted `/v1/cache` spec.
 
 ```sh
-npm install -D @vzn/vx @vzn/vx-migrate   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
+bun add -d @vzn/vx @vzn/vx-migrate
 ```
 
-In a Turbo or Nx repo, `npx @vzn/vx init --keep` runs this package, which
+In a Turbo or Nx repo, `bunx @vzn/vx init --keep` runs this package, which
 writes the `.vx/workspace.ts` that declares `turbo()` or `nx()`, installs
 what it imports and writes the lock. Where the repo shows a remote cache it
 declares `turboCache()` or `nxCache()` too; by hand it reads:
@@ -66,8 +66,8 @@ Rules:
 - `env` / `passThroughEnv`: explicit names go to `inputs.env` (env only) and `exec.env.passThrough` (both, plus both globals); a wildcard expands over the run's environment under `turbo()`, which maps where the tasks run (a new variable name such a wildcard matches maps afresh); the CLI, which writes for another environment, lists the names the task's package and its workspace dependencies spell (a root task: the whole repo; clerk's `E2E_*`), noted once per entry, and one nothing spells is a todo; `*` is the only wildcard, as in Turbo, so `\*`, a leading `\!`, `?` and `[` are literal: unkey's `NEXT_PUBLIC_\*` names one variable, which vx cannot key, so it is dropped and reported once for the workspace with the count of tasks naming it (openstatus's root `build` env `\*` had written one todo into each of 45 configs; `turbo()`: only when the run's environment sets it, as Turbo hashes nothing otherwise); and a `!` entry (openstatus' `!NEXT_PUBLIC_VERCEL_URL`) removes the names it matches from its list, with no todo, since vx matches no name it is not given. A name both a global list and the task's own list carry is listed once. A name that is no shell variable name (`p-q`) is keyed but left out of `exec.env.passThrough`, as `sh` drops it before the task runs.
 - Framework inference (Turbo hashes and passes Next's `NEXT_PUBLIC_*`, Vite's `VITE_*`, … for a package that depends on the framework): `turbo()` expands the prefix over the run's environment; the CLI writes the names the tracked source and `.env.example` of the package and its workspace dependencies spell (the bare prefix, as a `startsWith` test spells it, is none) (Next bundles theirs: cal.com's web, 23 alone, 58 with them), and a note asks for any only an installed dependency reads.
 
-- **Two tasks of one package on one output path** (strapi's `build`, `build:code` and `build:types`, all on `dist/**`): vx cleans a task's outputs before it runs and before a restore, so the loader refuses two cached tasks whose outputs provably overlap. Under vx's default `rules.exclusiveOutputs` an edge between the two changes nothing (twenty's `build:individual` writing into `build`'s `dist`). The mapping resolves it before the file is written — `build` keeps its cache, else the task with a `^` edge, else the first declared (typescript-eslint's `typecheck` has `^typecheck` and writes declarations into `build`'s `dist`: keeping it left `build` uncached); the rest run uncached with a todo naming the keeper and the fix, their own output path. A shared tsc incremental file (create-t3-turbo's `build` and `typecheck` both on `.cache/tsbuildinfo.json`) stays with the keeper alone, and the other task keeps its cache when it emits nothing else (a typecheck); one that emits more runs uncached, as `tsc --incremental` skips files the keeper's tsbuildinfo calls built. A keeper whose output is a directory at any depth (solid's build: `**/dist`) meets a sibling's tree (`coverage/**`) only at a `dist` inside it: the keeper takes that tree back with `!coverage/**` and both keep their cache, as under Turbo. Same rule for Nx targets.
-- **A task whose inputs read another task's outputs** (a `test` keyed on `**/*` beside a `build` writing `dist/**`): `vx lock` refuses it, since such a key cannot be known before the producer ran. Each overlapping output is taken back from the reader's inputs with `!` (`['**/*', '!dist/**']`), in package and workspace inputs alike, and a workspace output another package writes into this one is taken back from its package inputs too; Turbo and Nx hash what git tracks, and a build's outputs are not, so the key reads what the adopted tool read. A literal input another task writes cannot be taken back: that task runs uncached with a todo. A committed file under such an output is still a source: a reader the `!` would hide it from runs uncached with a todo. A keyed group (an `nx-input:<name>` twin, a transit node) runs nothing, so core lets it read what a task writes: it gets no `!` for a literal, the `!` that would hide a committed file goes, and it keeps its key (typescript-eslint's ast-spec commits the `*.shot` snapshots its `test` outputs, and its twin was written as `{}`, which core refuses). An output that names one committed file (eslint's `eslint-suppressions.json` in a `lint` task's outputs) is dropped, and so is the `!` each reader got for it: the file stays in every key, as Turbo and Nx hash it, and the readers stay cached. Same for Nx targets.
+- **Two tasks of one package on one output path** (strapi's `build`, `build:code` and `build:types`, all on `dist/**`): vx cleans a task's outputs before it runs and before a restore, so the loader refuses two cached tasks whose outputs provably overlap. Under vx's default `rules.exclusiveOutputs` an edge between the two changes nothing (twenty's `build:individual` writing into `build`'s `dist`). The mapping resolves it before the file is written — `build` keeps its cache, else the task with a `^` edge, else the first declared (typescript-eslint's `typecheck` has `^typecheck` and writes declarations into `build`'s `dist`: keeping it left `build` uncached); the rest run uncached with a todo naming the keeper and the fix, their own output path. A shared tsc incremental file (create-t3-turbo's `build` and `typecheck` both on `.cache/tsbuildinfo.json`) stays with the keeper alone, and the other task keeps its cache when it emits nothing else (a typecheck); one that emits more runs uncached, as `tsc --incremental` skips files the keeper's tsbuildinfo calls built. When either side is a directory at any depth (solid's build `**/dist`, its types `**/types`), the two meet only where one tree nests in the other: the keeper takes the sibling's glob back (`!coverage/**`, `!**/types`) and both keep their cache, as under Turbo. Same rule for Nx targets.
+- **A task whose inputs read another task's outputs** (a `test` keyed on `**/*` beside a `build` writing `dist/**`): `vx lock` refuses it, since such a key cannot be known before the producer ran. Each overlapping output is taken back from the reader's inputs with `!` (`['**/*', '!dist/**']`), in package and workspace inputs alike, and a workspace output another package writes into this one is taken back from its package inputs too; Turbo and Nx hash what git tracks, and a build's outputs are not, so the key reads what the adopted tool read. A literal input another task writes cannot be taken back: that task runs uncached with a todo. A committed file under such an output is still a source: a reader the `!` would hide it from runs uncached with a todo. A keyed group (an `inputs:<name>` twin, a transit node) runs nothing, so core lets it read what a task writes: it gets no `!` for a literal, the `!` that would hide a committed file goes, and it keeps its key (typescript-eslint's ast-spec commits the `*.shot` snapshots its `test` outputs, and its twin was written as `{}`, which core refuses). An output that names one committed file (eslint's `eslint-suppressions.json` in a `lint` task's outputs) is dropped, and so is the `!` each reader got for it: the file stays in every key, as Turbo and Nx hash it, and the readers stay cached. Same for Nx targets.
 - **Two packages' tasks on one workspace output** (cal.com's shared `post-install` writes `../../node_modules/@prisma/client/**` from every package with the script): core refuses two cached tasks on one path with no edge between them, so `turbo()` (and `nx()`) keeps the first (in package and task order) cached and runs the rest uncached, each with a todo naming the keeper. A package's own outputs count at their workspace path: typescript-eslint's root project caches `dist` and each package's typecheck `dist/packages/<name>`, one path twice. Edges across packages are not read, so an ordered pair loses its cache too.
 - `cache: false` or `persistent: true` → no `cache` block, the task still keyed on its `inputs` and `env` as Turbo hashes it; a persistent task gets `exec.persistent: {}` and, when some task depends on it, the consumer's `persistentTodo`.
 - A task's `description` (Turbo 2.11.5's schema) is the vx task's `description`.
@@ -91,7 +91,7 @@ import { nx } from '@vzn/vx-migrate'
 export default defineWorkspace({ plugins: [nx()] })
 ```
 
-Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every project's `build` target the way `nx run-many -t build` would. `nx()` is also the repo's edge source: each project's dependencies on Nx's graph (package deps, `implicitDependencies`, imports) are its `deps`, so `^build` follows Nx's order with no lockfile plugin. The plugin reads Nx's **resolved** project graph — where Nx has already applied `targetDefaults`, expanded `namedInputs`, inferred targets through its plugins and interpolated `{projectRoot}` and friends — so nothing is re-derived here. Per target: `nx:run-commands` and a plain `command` run as one shell line that does what Nx's run-commands does (below); `nx:run-script` is the package script, with the `$npm_package_name`, `$npm_package_version` and `$npm_lifecycle_event` it reads defined as `<pm> run` sets them (a migration reads the name and version from the manifest it imports, so a bump reaches them; any other `$npm_*` is a todo); `nx:noop` is a group task, and so is a target with neither an executor nor a command that has dependencies, as Nx normalizes it (one with none is dropped, as Nx drops it); **every other executor runs through `nx-exec`** with the executor and its options on the command line. Every target is keyed on its `inputs` (a target Nx does not cache on its own inputs alone, no `^` named inputs, since Nx folds no dependency's hash into it), and a target Nx caches (`cache: true`, or the legacy `cacheableOperations` list in `nx.json`) gets its `outputs` as the cache block, with no `inputs` meaning Nx's `default` and `^default`, named inputs resolved per project (nx.json's under the project's own; one neither defines, such as an `extends` preset not installed, keys the whole project with a todo, never an empty list that keys the task on its config alone), `{workspaceRoot}` / `{projectRoot}` / `{projectName}` interpolated anywhere in a path as Nx does (`{workspaceRoot}/coverage/{projectRoot}`), Nx's glob grammar translated (`*.[jt]s` is `*.{j,t}s`; the default `production` negation `?(*.)+(spec|test).[jt]s?(x)` becomes brace sets, a narrowing only a negation may take; what has no safe form is a todo), a project fileset of negations alone (nx-recipes' `noMarkdown`) starting from every project file, as Nx reads it, and an output outside the project dir (`dist/<project>` at the workspace root, Nx's default layout) a `workspaceFiles` output, an output outside the workspace (an old generator's `reportsDirectory: "../../coverage/<lib>"`) a todo and dropped, as vx caches only inside it, an output whose first segment is a wildcard (`{projectRoot}/**/*.d.ts`) cached, with the committed files it reaches kept (core never cleans one) and the rest cleaned before the run, and an output that covers the project's own `package.json` or vx.config cached with the file taken back by `!`; `dependsOn` becomes the edges (`^build` — dropped when no project has the target, as Nx gives it no edges and core refuses a `^name` nothing declares — `build`, `project:target` → `project#target`, everything past `project:` one target name, as Nx joins it (`ui:build:esm` is ui's `build:esm`; `ui:build:ci` names target `build:ci`, never `build`'s `ci` configuration, and is no edge where ui lacks it), this project's own target winning over a project name, `{ target, projects }` → each matched project's task, `projects` read as Nx's `findMatchingProjects` reads it: a name or a list of names, globs over names and over project directories (`libs/*`), `name:` / `tag:` / `directory:` labels, a bare word as a word in a name, and `!` exclusions; an edge to a target its project lacks is dropped without a word, as Nx drops it — `targetDefaults` that give every `typecheck` a `codegen` one project has; `^name` is every dependency's `name` whatever it holds, `^rsbuild:typecheck` included; a target glob — `test:e2e--*`, `^build-*`, `ui:build-{esm,cjs}`, a `{ target }` object's — expands over every target name in the workspace, as Nx 19.5+ does, before those rules; a same-project glob keeps its own project's matches), `{ env }` inputs pass through (one that is no shell variable name is keyed only), `{ runtime }` inputs run at the workspace root as Nx runs them (`inputs.workspaceRuntime`), with `{workspaceRoot}`, `{projectRoot}` and `{projectName}` written in as the paths and name they stand for (Nx runs the command as written, so `cat {workspaceRoot}/v.txt` keyed on cat's error there), and a command that exits non-zero keys its error and exit code and the task runs on, as Nx hashes its output whatever it exits (`git describe` in a repo with no tags): the written probe is `(<command>) || echo "exit $?"`, a `{ fileset, includeIgnored: true }` literal (Nx 23 hashes it from disk, gitignored or missing) is read by such a probe, since vx's globs see only what git lists, and a glob of one is a todo, a target that says `continuous` — or, in a graph from an Nx older than that field, runs a server executor (`@nx/vite:dev-server`, `@nx/next:server`, …) — is a persistent task and never cached, ready on spawn as Nx has it (Nx starts the dependents once it has started; a run-commands `readyWhen` gates them, below). The target's name never decides: a cached `dev` caches like any other target (nx#32610). `parallelism: false` (Nx runs the target alone) has no vx form and is a todo naming `--concurrency 1`; `syncGenerators` (Nx runs them first) is one workspace note per generator list, counting its tasks and naming `nx sync`; nx.json's `sync.globalGenerators` is one note per run naming `nx sync`. A target with `configurations` is one task per configuration (one whose name another target holds, `vite`'s `build` beside an inferred `vite:build`, is not written, with a todo, as Nx resolves `a:vite:build` to the target): `build` carries the default configuration's options, `build:ci` the `ci` one, and an edge of `build:ci` (own, named or `^`) reaches each target's `ci` task where it declares one, else its default, as Nx's `resolveConfiguration` does; a `^build` there becomes one edge per dependency Nx links. A `^name` input (`^production`, `{ input, dependencies: true }`, the pre-17 `{ input, projects: "dependencies" }`; `projects: "self"` is the own input, as Nx 23 still reads both) is what Nx hashes: each dependency's `name`, over the project graph, whether or not a task edge exists. A `{ input, projects }` list is read as `dependsOn`'s `projects` is. Each project some reader reaches gets an `nx-input:<name>` task — a keyed group (no command, nothing spawns, not counted in the run summary) keyed on its own `name` input, depending on its Nx dependencies' twins (a project nothing reaches gets none) — and a task that reads `^name` depends on its direct dependencies' twins, so the whole closure folds into its key with each project hashed once. A dependency FILESET (`^{projectRoot}/tsconfig.lib.json`, `{ fileset, dependencies: true }`, which Nx's own inferred `typecheck` writes) folds the same way: its twin, `nx-input:fileset-<hash>` (a glob's `*` is no task name; the task's description names the fileset), keys on that fileset in each project. A twin lists its project's `package.json` and `project.json` first (whichever exists; Nx keys every task on its project's manifest and configuration): a fileset that matches nothing (an absent `tsconfig.spec.json`, a dependency's unbuilt `*.d.ts`) is nothing to Nx and no "matched no files" warning, and the file appearing re-keys its readers. The twins spawn nothing and stay out of a run's output and task count, so `vx run build` counts the tasks `nx run-many -t build` does. A path input inside an output one of the project's own targets declares (TanStack/table's `public` input lists `{projectRoot}/dist`) is generated, and gitignored where Nx caches it: Nx's file map skips gitignored files, so Nx hashes nothing there (a changed `dist` file is a cache hit under Nx 23.3), and it is dropped without a todo, and the task that writes it keys its dependants through `dependsOn`.
+Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every project's `build` target the way `nx run-many -t build` would. `nx()` is also the repo's edge source: each project's dependencies on Nx's graph (package deps, `implicitDependencies`, imports) are its `deps`, so `^build` follows Nx's order with no lockfile plugin. The plugin reads Nx's **resolved** project graph — where Nx has already applied `targetDefaults`, expanded `namedInputs`, inferred targets through its plugins and interpolated `{projectRoot}` and friends — so nothing is re-derived here. Per target: `nx:run-commands` and a plain `command` run as one shell line that does what Nx's run-commands does (below); `nx:run-script` is the package script, with the `$npm_package_name`, `$npm_package_version` and `$npm_lifecycle_event` it reads defined as `<pm> run` sets them (a migration reads the name and version from the manifest it imports, so a bump reaches them; any other `$npm_*` is a todo); `nx:noop` is a group task, and so is a target with neither an executor nor a command that has dependencies, as Nx normalizes it (one with none is dropped, as Nx drops it); **every other executor runs through `nx-exec`** with the executor and its options on the command line. Every target is keyed on its `inputs` (a target Nx does not cache on its own inputs alone, no `^` named inputs, since Nx folds no dependency's hash into it), and a target Nx caches (`cache: true`, or the legacy `cacheableOperations` list in `nx.json`) gets its `outputs` as the cache block, with no `inputs` meaning Nx's `default` and `^default`, named inputs resolved per project (nx.json's under the project's own; one neither defines, such as an `extends` preset not installed, keys the whole project with a todo, never an empty list that keys the task on its config alone), `{workspaceRoot}` / `{projectRoot}` / `{projectName}` interpolated anywhere in a path as Nx does (`{workspaceRoot}/coverage/{projectRoot}`), Nx's glob grammar translated (`*.[jt]s` is `*.{j,t}s`; the default `production` negation `?(*.)+(spec|test).[jt]s?(x)` becomes brace sets, a narrowing only a negation may take; what has no safe form is a todo), a project fileset of negations alone (nx-recipes' `noMarkdown`) starting from every project file, as Nx reads it, and an output outside the project dir (`dist/<project>` at the workspace root, Nx's default layout) a `workspaceFiles` output, an output outside the workspace (an old generator's `reportsDirectory: "../../coverage/<lib>"`) a todo and dropped, as vx caches only inside it, an output whose first segment is a wildcard (`{projectRoot}/**/*.d.ts`) cached, with the committed files it reaches kept (core never cleans one) and the rest cleaned before the run, and an output that covers the project's own `package.json` or vx.config cached with the file taken back by `!`; `dependsOn` becomes the edges (`^build` — dropped when no project has the target, as Nx gives it no edges and core refuses a `^name` nothing declares — `build`, `project:target` → `project#target`, everything past `project:` one target name, as Nx joins it (`ui:build:esm` is ui's `build:esm`; `ui:build:ci` names target `build:ci`, never `build`'s `ci` configuration, and is no edge where ui lacks it), this project's own target winning over a project name, `{ target, projects }` → each matched project's task, `projects` read as Nx's `findMatchingProjects` reads it: a name or a list of names, globs over names and over project directories (`libs/*`), `name:` / `tag:` / `directory:` labels, a bare word as a word in a name, and `!` exclusions; an edge to a target its project lacks is dropped without a word, as Nx drops it — `targetDefaults` that give every `typecheck` a `codegen` one project has; `^name` is every dependency's `name` whatever it holds, `^rsbuild:typecheck` included; a target glob — `test:e2e--*`, `^build-*`, `ui:build-{esm,cjs}`, a `{ target }` object's — expands over every target name in the workspace, as Nx 19.5+ does, before those rules; a same-project glob keeps its own project's matches), `{ env }` inputs pass through (one that is no shell variable name is keyed only), `{ runtime }` inputs run at the workspace root as Nx runs them (`inputs.workspaceRuntime`), with `{workspaceRoot}`, `{projectRoot}` and `{projectName}` written in as the paths and name they stand for (Nx runs the command as written, so `cat {workspaceRoot}/v.txt` keyed on cat's error there), and a command that exits non-zero keys its error and exit code and the task runs on, as Nx hashes its output whatever it exits (`git describe` in a repo with no tags): the written probe is `(<command>) || echo "exit $?"`, a `{ fileset, includeIgnored: true }` literal (Nx 23 hashes it from disk, gitignored or missing) is read by such a probe, since vx's globs see only what git lists, and a glob of one is a todo, a target that says `continuous` — or, in a graph from an Nx older than that field, runs a server executor (`@nx/vite:dev-server`, `@nx/next:server`, …) — is a persistent task and never cached, ready on spawn as Nx has it (Nx starts the dependents once it has started; a run-commands `readyWhen` gates them, below). The target's name never decides: a cached `dev` caches like any other target (nx#32610). `parallelism: false` (Nx runs the target alone) has no vx form and is a todo naming `--concurrency 1`; `syncGenerators` (Nx runs them first) is one workspace note per generator list, counting its tasks and naming `nx sync`; nx.json's `sync.globalGenerators` is one note per run naming `nx sync`. A target with `configurations` is one task per configuration (one whose name another target holds, `vite`'s `build` beside an inferred `vite:build`, is not written, with a todo, as Nx resolves `a:vite:build` to the target): `build` carries the default configuration's options, `build:ci` the `ci` one, and an edge of `build:ci` (own, named or `^`) reaches each target's `ci` task where it declares one, else its default, as Nx's `resolveConfiguration` does; a `^build` there becomes one edge per dependency Nx links. A `^name` input (`^production`, `{ input, dependencies: true }`, the pre-17 `{ input, projects: "dependencies" }`; `projects: "self"` is the own input, as Nx 23 still reads both) is what Nx hashes: each dependency's `name`, over the project graph, whether or not a task edge exists. A `{ input, projects }` list is read as `dependsOn`'s `projects` is. Each project some reader reaches gets an `inputs:<name>` task — a keyed group (no command, nothing spawns, not counted in the run summary) keyed on its own `name` input, depending on its Nx dependencies' twins (a project nothing reaches gets none) — and a task that reads `^name` depends on its direct dependencies' twins, so the whole closure folds into its key with each project hashed once. A dependency FILESET (`^{projectRoot}/tsconfig.lib.json`, `{ fileset, dependencies: true }`, which Nx's own inferred `typecheck` writes) folds the same way: its twin, `inputs:fileset-<hash>` (a glob's `*` is no task name; the task's description names the fileset), keys on that fileset in each project. A twin lists its project's `package.json` and `project.json` first (whichever exists; Nx keys every task on its project's manifest and configuration): a fileset that matches nothing (an absent `tsconfig.spec.json`, a dependency's unbuilt `*.d.ts`) is nothing to Nx and no "matched no files" warning, and the file appearing re-keys its readers. The twins spawn nothing and stay out of a run's output and task count, so `vx run build` counts the tasks `nx run-many -t build` does. A path input inside an output one of the project's own targets declares (TanStack/table's `public` input lists `{projectRoot}/dist`) is generated, and gitignored where Nx caches it: Nx's file map skips gitignored files, so Nx hashes nothing there (a changed `dist` file is a cache hit under Nx 23.3), and it is dropped without a todo, and the task that writes it keys its dependants through `dependsOn`.
 
 | Option  | Meaning                                                                                                                                                      |
 | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -147,7 +147,7 @@ Nx loads a task's `.env` files into its environment — the project's before the
 
 ### The target a task sees
 
-Every task gets `NX_TASK_TARGET_PROJECT`, `NX_TASK_TARGET_TARGET`, `LERNA_PACKAGE_NAME` (the project, which Lerna on Nx's runner documents to scripts) and, where it runs a configuration, `NX_TASK_TARGET_CONFIGURATION` in `exec.env.define`, as Nx hands them to every task; a run-commands `env` wins. A package script's `nx exec -- <cmd>` reads them: without them it starts Nx's own task runner, which runs the target and its dependencies again.
+A task whose command still runs Nx or Lerna (`nx-exec`, `nx-env`, `nx exec`, `lerna`) or names one of them gets `NX_TASK_TARGET_PROJECT`, `NX_TASK_TARGET_TARGET`, `LERNA_PACKAGE_NAME` (the project, which Lerna on Nx's runner documents to scripts) and, where it runs a configuration, `NX_TASK_TARGET_CONFIGURATION` in `exec.env.define`, as Nx hands them to every task; a run-commands `env` wins. Any other task gets none. Nx's own `npm:public` / `npm:private` tags are not written. A package script's `nx exec -- <cmd>` reads them: without them it starts Nx's own task runner, which runs the target and its dependencies again.
 
 ### Inputs that key nothing here
 
@@ -226,11 +226,11 @@ bunx @vzn/vx-migrate --keep    # keep turbo.json / nx.json as the source: turbo(
 bunx @vzn/vx-migrate --help    # the usage, exit 0
 ```
 
-It is the one command a repo needs (`pnpx @vzn/vx-migrate` in a pnpm repo works the same):
+It is the one command a repo needs (`pbunx @vzn/vx-migrate` in a pnpm repo works the same):
 
 - In a Turbo or Nx repo, in a terminal, it asks which adoption you want: **native** (the default, a `vx.config.ts` per package) or **keep** (a workspace file declaring `turbo()` or `nx()`). `--native` / `--keep` answer it; with no terminal (CI, a pipe) it is native. Elsewhere both are refused. A repo already set up (a workspace file declaring neither, and project configs) is said to be, exit 0, unless `--force`.
 - Native or keep, a remote cache the repo shows is declared: `turboCache()` for turbo.json's enabled `remoteCache`, a `turbo link`ed `.turbo/config.json` or a CI file (`.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/config.yml`) setting `TURBO_TOKEN`; `nxCache()` for one setting `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. The report names the file that showed it. Nx Cloud (`nxCloudId`, `nxCloudAccessToken`, the `nx-cloud` runner) is named instead: vx does not speak its wire.
-- With no `.vx/workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): the remote cache above, the `@vzn/vx-lockfile` factory for the lockfile (`pnpm()`, `bun()`, `npm()`, `yarn()`), `scheduleHistoryPlugin()`, and `github()` when `.github/workflows` exists, from `@vzn/vx-ci`, each installed beside `@vzn/vx` at vx-migrate's own version. Keep adds them to the file it writes, or to one already in that shape; any other workspace file is the user's and left alone. Native over a file vx wrote (a keep adoption's) rewrites it: `turbo()` and `nx()` go, since the configs written replace them, and the other plugins stay.
+- With no `.vx/workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): the remote cache above, the `@vzn/vx-lockfile` factory for the lockfile (`bun()`, `pnpm()`, `npm()`, `yarn()`), `scheduleHistoryPlugin()`, and `github()` when `.github/workflows` exists, from `@vzn/vx-ci`, each installed beside `@vzn/vx` at vx-migrate's own version. Keep adds them to the file it writes, or to one already in that shape; any other workspace file is the user's and left alone. Native over a file vx wrote (a keep adoption's) rewrites it: `turbo()` and `nx()` go, since the configs written replace them, and the other plugins stay.
 - It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, every `@vzn/vx-*` package the workspace file imports (one an earlier init wrote included), and `@vzn/vx-migrate` for keep or when a written task runs its `nx-exec` or `nx-env` bin (`pnpm add -D -w`, `yarn add -D -W` on Yarn 1 and without `-W` on Yarn 2+, `bun add -d`, `npm install -D`). A package the root both lists and has installed at vx-migrate's own version is left alone; any other is installed at that version, and so is every other `@vzn/vx-*` plugin the root lists from the registry (one install moves them together, as `vx upgrade` does). Native removes a listed `@vzn/vx-migrate` when nothing written needs it (no `nx-exec` / `nx-env` task, no `turboCache()` or `nxCache()` left in the workspace file): `pnpm remove -w`, `yarn remove` (`-W` on Yarn 1), `bun remove`, `npm uninstall`. `--no-install` skips both. vx-migrate runs only with the `@vzn/vx` of its own release, which it installs: one of another release (a `bun x` install directory keeps the one it had) is refused, naming where it was loaded.
 - Native, once the files are written, it ends with `vx lock`: `.vx/projects.lock.json` is written and the graph rules are checked, its line the report's `lock` row. A refusal prints above the report and the configs stay written (exit 0). `--no-install` skips it, since the plugins the workspace file declares are not installed yet, and `next` then starts with `vx lock`.
 
@@ -284,7 +284,7 @@ Detected when the root `package.json` lists `vite-plus`, after turbo.json and Nx
 Where no runner's config is the source (or under `--from scripts`), each
 package's `package.json` scripts become its `vx.config.ts`, plus a
 `.vx/workspace.ts` that declares the `@vzn/vx-lockfile` plugin for the lockfile at
-the root (`pnpm()`, `bun()`, `npm()` or `yarn()`; `{ plugins: [] }`
+the root (`bun()`, `pnpm()`, `npm()` or `yarn()`; `{ plugins: [] }`
 without one): package edges (`^build`, `--affected`) come from it.
 Running and caching here are the floor, so it declares no executor or
 cache, and the file carries no comment (it is the user's). When
@@ -497,11 +497,8 @@ order may matter, so it is not made a group.
 The report lists each TODO once per reason: tasks that share one are
 named together (the first five, then a count; the files carry each),
 and when no task caches it says uncommenting a TODO task's cache line
-makes the second run a hit. Its `next:` line is a command the user can type: the
-runner that started vx (`npx`, `pnpm`, `yarn`, `bunx`, read from
-`npm_config_user_agent`) with the installed `vx` bin, else the
-`@vzn/vx` package (`npx` under Yarn 1, which has no `dlx`); with no
-runner, a bare `vx`. Outside a git work tree it starts with
+makes the second run a hit. Its `next:` line is a command the user can type,
+with a bare `vx` (`vx init` installs it). Outside a git work tree it starts with
 `git init`, and with no script mapped with declaring a task, since the
 run would refuse without either. It runs `build`, else the first task that
 neither serves (`persistent`) nor changes the repo (`clean`, `release`,
@@ -550,7 +547,7 @@ export default defineWorkspace({
 
 Off CI a run reads the remote and does not write it unless its policy names the remote. Give the write token only to the default branch's CI and a read-only one to laptops and pull request jobs: the server's token is the boundary (`docs/security.md` § Cache poisoning). The same holds for `nxCache()`.
 
-Every option falls back to the tool's own environment variable, so a self-hosted setup carries over unchanged. A token with no `apiUrl` means Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as it does for `turbo` — so `npx turbo login && npx turbo link`, then `turboCache()` with `TURBO_TOKEN` / `TURBO_TEAM` set, is the whole hosted setup. Below the environment, in Turbo's order: a Vercel build's `VERCEL_ARTIFACTS_TOKEN` and `VERCEL_ARTIFACTS_OWNER` (the team id, where `TURBO_TOKEN` with a team is not set), then the repo's `.turbo/config.json` (what `turbo link` writes: `apiUrl`, `teamId`, `teamSlug`, `token`), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. A team with no `apiUrl` also means Vercel's. With a URL or a team but no token, the token comes from the OS keychain ([Tokens](#tokens-and-the-os-keychain)); with none of the three the plugin **declines** and the run stays local.
+Every option falls back to the tool's own environment variable, so a self-hosted setup carries over unchanged. A token with no `apiUrl` means Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as it does for `turbo` — so `bunx turbo login && bunx turbo link`, then `turboCache()` with `TURBO_TOKEN` / `TURBO_TEAM` set, is the whole hosted setup. Below the environment, in Turbo's order: a Vercel build's `VERCEL_ARTIFACTS_TOKEN` and `VERCEL_ARTIFACTS_OWNER` (the team id, where `TURBO_TOKEN` with a team is not set), then the repo's `.turbo/config.json` (what `turbo link` writes: `apiUrl`, `teamId`, `teamSlug`, `token`), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. A team with no `apiUrl` also means Vercel's. With a URL or a team but no token, the token comes from the OS keychain ([Tokens](#tokens-and-the-os-keychain)); with none of the three the plugin **declines** and the run stays local.
 
 | Option            | Environment variable                                                                                                                     | Meaning                                                                                                                                                                                                                                                                       |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -564,6 +561,7 @@ Every option falls back to the tool's own environment variable, so a self-hosted
 | `uploadTimeoutMs` | `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`, then `remoteCache.uploadTimeout` (seconds)                                                          | PUT deadline (default 60 s; 0 none)                                                                                                                                                                                                                                           |
 | `retries`         | —                                                                                                                                        | resends of a request answered 5xx (not 501) or never connected (default 1, Turbo's); a 429 waits out the limit; 0 turns both off                                                                                                                                              |
 | `preflight`       | `TURBO_PREFLIGHT` (1 or 0), then `remoteCache.preflight`                                                                                 | send Turbo's `OPTIONS` preflight before each artifact request and go where its `Location` points (relative to `apiUrl`); the token goes along only when the API's `Access-Control-Allow-Headers` admits `Authorization`; a redirected preflight is not followed (default off) |
+| `scope`           | —                                                                                                                                        | `RemoteScope`: `'header'` (default): every read names the run's refs, own branch first, in `x-artifact-read-scopes`; `'key'`: each entry is keyed on its ref, a read asks every ref's key in one batch (a server that ignores the header)                                     |
 
 The signature is Turbo's current scheme (`artifact-signature:v2`: prefix, hash, team id and body, each length-prefixed, under HMAC-SHA256, base64 in `x-artifact-tag`). A signed body is written to a temp file before its tag can be checked, so one past core's artifact ceiling (2 GiB, at zstd's bound) is refused as it passes it, and is a miss.
 
@@ -620,7 +618,7 @@ With no token from an option, a variable or a config file, both plugins read the
 
 ## Remote-cache behaviour (both)
 
-- Every request (`HEAD`, `GET`, `PUT`, the batch `POST`) carries `x-vx-cache-scope`: `trusted` for a task's own key, else the branch scope its key was derived in (`acme/app:feat-x`). The key is the same either way. A server that keeps one bucket per scope uses it to skip its own layering; whether a write to `trusted` is allowed stays the server's call, from the token (a CI ID token). A request without the header, from an older client, leaves the layering to the server. A batch that mixes scopes is one `POST` per scope.
+- Task keys carry no branch. `turboCache()` names the run's refs on every read (`HEAD`, `GET`, the batch `POST`) in `x-artifact-read-scopes`, own branch first (`refs/heads/feat-x, refs/heads/main`): from CI's env, else git's current branch, then the default branch. A `PUT` names none: where a write lands is the server's call, from the CI OIDC token checked against its trust policy. `scope: 'key'` folds the ref into each key instead, for a server that ignores the header. `nxCache()` sends plain requests. How a server implements the header: [Branch caches a server enforces](https://vznjs.github.io/vx/blog/branch-caches-a-server-enforces/).
 - A remote error degrades to a **miss** and a warning that names the request, the artifact and the server — `[vx] plugin '@vzn/vx-migrate': upload 32248a2a7c89e241 to https://cache.example.com/v8/artifacts failed: no answer within 60000 ms` — never the token. The run never fails because of the cache.
 - The same failure is said once per run: an unreachable server fails the probe, the download and the upload alike, and the run prints the first and, at its end, `[vx] plugin '@vzn/vx-migrate': 2 more requests failed the same way: Unable to connect. Is the computer able to access the url?` (core does the counting, for every cache plugin).
 - A request answered `5xx` (not `501`), or one that never connected (a refused port, an unresolved host), is sent again after 2 s, `retries` times. A `429` pauses every request to that remote for its `Retry-After` (capped at 10 s a wait, 2 s without one), and the request is sent again when the pause ends, for up to 20 s from its first `429`, as Turbo's client does. A spent deadline is not resent: it has already cost its wait.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.644",
+  "version": "0.0.646",
   "license": "MIT",
   "description": "Adopt @vzn/vx from Turborepo, Nx or package.json scripts: run the repo unchanged, migrate it to vx.config.ts, and keep your Turbo or Nx remote cache",
   "keywords": [
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.644"
+    "@vzn/vx": "^0.0.646"
   },
   "repository": {
     "type": "git",

package/src/adoption-plugin.ts

@@ -6,7 +6,7 @@
 // skeleton until item 592; what differs is only how the mapping is made.
 
 import { definePlugin, type ProjectHookContext, type VxPlugin } from '@vzn/vx'
-import { type AdoptionMapping, cachedMapping } from './mapping-cache.js'
+import { type AdoptionMapping, cachedMapping, codeId } from './mapping-cache.js'
 import { warnGaps } from './plugin-gaps.js'
 import { headStamp, spareTrackedOutputs, trackedFiles } from './tracked-outputs.js'
 
@@ -76,18 +76,16 @@ export function adoptionPlugin(
     async project(config, ctx) {
       if (mappedFor !== ctx.projects) {
         mappedFor = ctx.projects
+        // The key's other reads overlap the plugin's own.
+        void codeId()
+        const stamp = headStamp(ctx.workspaceRoot)
         mapping = mapRun(ctx).then(async (r) =>
           r.spareTracked === true
-            ? cachedMapping(
-                ctx.cacheDir,
-                r.name,
-                [...r.reads, await headStamp(ctx.workspaceRoot)],
-                async () => {
-                  let read: Promise<readonly string[] | null> | undefined
-                  const tracked = () => (read ??= trackedFiles(ctx.workspaceRoot))
-                  return spare(ctx, await r.map(tracked), await tracked())
-                },
-              )
+            ? cachedMapping(ctx.cacheDir, r.name, [...r.reads, await stamp], async () => {
+                let read: Promise<readonly string[] | null> | undefined
+                const tracked = () => (read ??= trackedFiles(ctx.workspaceRoot))
+                return spare(ctx, await r.map(tracked), await tracked())
+              })
             : cachedMapping(ctx.cacheDir, r.name, r.reads, () =>
                 r.map(() => trackedFiles(ctx.workspaceRoot)),
               ),

package/src/index.ts

@@ -2,14 +2,40 @@
 // runs unchanged) and the two remote caches speaking Turbo's and Nx's
 // wire. The CLI (`bunx @vzn/vx-migrate`) is `migrate.ts`; mappers and
 // cache clients are internal (1.0 freezes what this file exports).
-export { turbo, type TurboPluginOptions } from './turbo/index.js'
-export {
-  nx,
-  type NxExecutors,
-  type NxExecutorTarget,
-  type NxExecutorTranslation,
-  type NxExecutorTranslator,
-  type NxPluginOptions,
+//
+// Each factory loads its module on first call: a workspace evaluates this
+// file on every run, and a Turbo repo paid ~4 ms per run transpiling nx()
+// and both cache clients it never calls (solid, 2026-10-22).
+import type { VxPlugin } from '@vzn/vx'
+import type * as Turbo from './turbo/index.js'
+import type { TurboPluginOptions } from './turbo/index.js'
+import type { NxPluginOptions } from './nx/index.js'
+import type { TurboCacheOptions } from './turbo-cache/index.js'
+import type { NxCacheOptions } from './nx-cache/index.js'
+import type * as Nx from './nx/index.js'
+import type * as TurboCache from './turbo-cache/index.js'
+import type * as NxCache from './nx-cache/index.js'
+
+export type { TurboPluginOptions } from './turbo/index.js'
+export type {
+  NxExecutors,
+  NxExecutorTarget,
+  NxExecutorTranslation,
+  NxExecutorTranslator,
+  NxPluginOptions,
 } from './nx/index.js'
-export { turboCache, type TurboCacheOptions } from './turbo-cache/index.js'
-export { nxCache, type NxCacheOptions } from './nx-cache/index.js'
+export type { TurboCacheOptions } from './turbo-cache/index.js'
+export type { NxCacheOptions } from './nx-cache/index.js'
+
+export function turbo(options: TurboPluginOptions = {}): VxPlugin {
+  return (require('./turbo/index.js') as typeof Turbo).turbo(options)
+}
+export function nx(options: NxPluginOptions = {}): VxPlugin {
+  return (require('./nx/index.js') as typeof Nx).nx(options)
+}
+export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
+  return (require('./turbo-cache/index.js') as typeof TurboCache).turboCache(options)
+}
+export function nxCache(options: NxCacheOptions = {}): VxPlugin {
+  return (require('./nx-cache/index.js') as typeof NxCache).nxCache(options)
+}

package/src/mapping-cache.ts

@@ -8,6 +8,7 @@
 // package's sources and the core helpers the mappers call: a new
 // `@vzn/vx-migrate` or `@vzn/vx` maps afresh.
 
+import { statSync } from 'node:fs'
 import { mkdir, rename } from 'node:fs/promises'
 import path from 'node:path'
 import { foldScriptHooks, isLiteralPattern, outputsOverlap, VERSION } from '@vzn/vx'
@@ -30,8 +31,8 @@ export interface AdoptionMapping {
 
 let code: Promise<string> | undefined
 
-/** This package's sources and the core helpers the mappers call, hashed once per process. */
-function codeId(): Promise<string> {
+/** This package's sources (by size and mtime) and the core helpers the mappers call, once per process. */
+export function codeId(): Promise<string> {
   code ??= (async () => {
     const parts: string[] = [
       VERSION,
@@ -40,7 +41,13 @@ function codeId(): Promise<string> {
     const files: string[] = []
     for await (const f of new Bun.Glob('**/*.{ts,cjs}').scan(import.meta.dir)) files.push(f)
     files.sort()
-    for (const f of files) parts.push(f, await Bun.file(path.join(import.meta.dir, f)).text())
+    // Size and mtime, not bytes: reading the 650 kB of sources cost ~10 ms
+    // on every run, more than the mapping hit it guards saves on a small
+    // repo (solid, 2026-10-22). An edit moves both.
+    for (const f of files) {
+      const s = statSync(path.join(import.meta.dir, f))
+      parts.push(f, `${s.size}:${s.mtimeMs}`)
+    }
     return hex(parts.join('\0'))
   })()
   return code
@@ -71,11 +78,12 @@ export async function cachedMapping(
   parts: readonly string[],
   map: () => Promise<AdoptionMapping>,
 ): Promise<AdoptionMapping> {
-  const key = hex([await codeId(), ...parts].join('\0'))
   const file = path.join(cacheDir, `vx-migrate-${name}-mapping.json`)
-  const held = (await Bun.file(file)
+  const reading = Bun.file(file)
     .json()
-    .catch(() => null)) as Held | null
+    .catch(() => null) as Promise<Held | null>
+  const key = hex([await codeId(), ...parts].join('\0'))
+  const held = await reading
   if (held?.key === key) {
     return {
       byName: new Map(held.byName),

package/src/migrate-turbo.ts

@@ -12,12 +12,8 @@ import {
   quoteTsLiteral as quote,
 } from '@vzn/vx'
 import type { PackageMeta } from './packages.js'
-import {
-  mapTurboWorkspace,
-  rootTaskProject,
-  type TurboGlobal,
-  type TurboMappedProject,
-} from './turbo/turbo-map.js'
+import { mapTurboWorkspace, type TurboGlobal, type TurboMappedProject } from './turbo/turbo-map.js'
+import { rootTaskProject } from './turbo/turbo-reads.js'
 import { relPosix } from './paths.js'
 import { gitIgnored, spareTrackedOutputs, trackedFiles, trackedKinds } from './tracked-outputs.js'
 import { DOTENV_GLOBS_HEAD, DOTENV_PROBE, DOTENV_PROBE_TOP } from './dotenv-probe.js'

package/src/migrate.ts

@@ -53,14 +53,13 @@ import {
   missingPackages,
   MODE_QUESTION,
   ownVersion,
-  type PackageManager,
   packageManagerOf,
   parseModeAnswer,
   uninstall,
 } from './adopt.js'
 import { migrateTurbo } from './migrate-turbo.js'
 import { migrateViteTask } from './migrate-vite-task.js'
-import { turboConfigFile } from './turbo/turbo-map.js'
+import { turboConfigFile } from './turbo/turbo-reads.js'
 import { lockfilePlugin } from './workspace-notes.js'
 import {
   extendWorkspaceFile,
@@ -642,14 +641,6 @@ function lockRow(lock: { code: number; said: string }): ui.FieldRow {
 /** `.vx/.gitignore`'s text, as core writes it: the machine-local cache and restore staging stay out of git. */
 const DOT_VX_GITIGNORE = '/cache\n/tmp\n'
 
-// npx and bunx name the package: their bare `vx` is a stranger's npm package.
-const EXEC: Record<PackageManager, string> = {
-  pnpm: 'pnpm vx',
-  yarn: 'yarn vx',
-  bun: 'bunx @vzn/vx',
-  npm: 'npx @vzn/vx',
-}
-
 /**
  * Install what the workspace file imports, if missing, then run the repo's
  * build. Pinned to this release: every @vzn package releases in lockstep,
@@ -666,12 +657,12 @@ export function adoptionNext(
   const missing = needs.filter(
     (p) => !existsSync(path.join(root, 'node_modules', p, 'package.json')),
   )
-  // A global vx (no runner started this one) runs the workspace's plugins as they are.
-  const vx = process.env['npm_config_user_agent'] === undefined ? 'vx' : EXEC[pm]
-  const run = `${vx} run ${firstTask(path.join(root, source), runner)} --all`
+  // `vx init` installs vx globally first: vx alone, never a package
+  // manager's runner (owner, 2026-10-22: vx owns the command).
+  const run = `vx run ${firstTask(path.join(root, source), runner)} --all`
   if (missing.length === 0) return run
   const pinned = version === null ? missing : missing.map((p) => `${p}@${version}`)
-  return `${installArgv(root, pm, pinned).join(' ')} && ${vx} lock && ${run}`
+  return `${installArgv(root, pm, pinned).join(' ')} && vx lock && ${run}`
 }
 
 /**

package/src/nx/nx-map.ts

@@ -284,11 +284,20 @@ export interface NxMapping {
   readonly notes: string[]
 }
 
-/** A node's tags as vx takes them: a blank one would be refused at load. */
+/** A command that still runs Nx or Lerna (`nx-exec`, `nx-env`, `nx exec`, `lerna run`) or reads what they set. */
+const RUNS_NX = /(?:^|[\s;&|('"/])(?:nx(?:-exec|-env)?|lerna)\s|NX_TASK_TARGET_|LERNA_PACKAGE_NAME/
+
+/**
+ * A node's tags as vx takes them: a blank one would be refused at load, and
+ * `npm:public` / `npm:private` are Nx's own, read off package.json.
+ */
 function nxTags(node: NxNode | undefined): string[] {
   const tags = node?.data?.tags
   return Array.isArray(tags)
-    ? tags.filter((t): t is string => typeof t === 'string' && t.trim() !== '')
+    ? tags.filter(
+        (t): t is string =>
+          typeof t === 'string' && t.trim() !== '' && t !== 'npm:public' && t !== 'npm:private',
+      )
     : []
 }
 
@@ -481,7 +490,7 @@ export async function mapNxWorkspace(
     }
     mapped.push({ meta, tasks })
   }
-  // The `nx-input:<name>` twins the `^` inputs above asked for, in every
+  // The `inputs:<name>` twins the `^` inputs above asked for, in every
   // project a graph node owns — one with no targets too.
   const byMeta = new Map(mapped.map((m) => [m.meta, m]))
   for (const [nodeName, list] of upstream.inputTasks()) {
@@ -898,7 +907,7 @@ function buildTask(
   // saw nothing the task reads, and a changed document replayed the old
   // generated client (Growth, 2026-10-16).
   const orphanReader =
-    inputs.dependentOutputs.length > 0 && !deps.some((d) => !d.includes('#nx-input:'))
+    inputs.dependentOutputs.length > 0 && !deps.some((d) => !d.includes('#inputs:'))
   if (orphanReader && cacheWanted && !persistent) {
     todos.push(orphanReaderTodo(inputs.dependentOutputs, target.dependsOn))
   }
@@ -967,18 +976,24 @@ function buildTask(
   // `nx exec -- <cmd>`, a package script's way to run under Nx, reads it:
   // unset, it booted Nx's own task runner, which ran the target and its
   // dependencies again. `LERNA_PACKAGE_NAME` is the project too: Lerna
-  // runs on Nx's runner and documents it to scripts. A run-commands `env`
-  // still wins, as in Nx.
-  env.define = {
-    NX_TASK_TARGET_PROJECT: projectName,
-    NX_TASK_TARGET_TARGET: targetName,
-    LERNA_PACKAGE_NAME: projectName,
-    ...(variant.configuration === undefined
-      ? {}
-      : { NX_TASK_TARGET_CONFIGURATION: variant.configuration }),
+  // runs on Nx's runner and documents it to scripts. Only a command that
+  // still runs Nx or Lerna gets them: a native task names no other runner
+  // (owner, 2026-10-22). A run-commands `env` still wins, as in Nx.
+  const define = {
+    ...(RUNS_NX.test(mapped.command)
+      ? {
+          NX_TASK_TARGET_PROJECT: projectName,
+          NX_TASK_TARGET_TARGET: targetName,
+          LERNA_PACKAGE_NAME: projectName,
+          ...(variant.configuration === undefined
+            ? {}
+            : { NX_TASK_TARGET_CONFIGURATION: variant.configuration }),
+        }
+      : {}),
     ...mapped.env,
   }
-  exec.env = env
+  if (Object.keys(define).length > 0) env.define = define
+  if (Object.keys(env).length > 0) exec.env = env
   if (mapped.timeout !== undefined) exec.timeout = mapped.timeout
   if (readyWhen !== undefined) {
     exec.persistent = { readyWhen }
@@ -1040,7 +1055,7 @@ function reachesProducer(
   if (!Array.isArray(deps)) return false
   return deps.some((d) => {
     if (typeof d !== 'string' || d.includes('*')) return true
-    if (d.includes('#nx-input:')) return false
+    if (d.includes('#inputs:')) return false
     if (d.startsWith('^'))
       return [...reached(project)].some((p) => emittedIds.has(`${p}#${d.slice(1)}`))
     return d.includes('#') || emittedIds.has(`${project}#${d}`)

package/src/nx/nx-upstream.ts

@@ -2,7 +2,7 @@
 // dependency's `name` input for every project the graph reaches, whether or
 // not a task edge exists, so a `test` with `^production` and no `dependsOn`
 // re-keys on a dependency's source. vx folds upstream KEYS along
-// `dependsOn`, so each project gets one `nx-input:<name>` task — a keyed
+// `dependsOn`, so each project gets one `inputs:<name>` task — a keyed
 // group, keyed on the project's own `name` input — with an edge to its
 // dependencies' twin. A task that reads `^name` depends on its direct
 // dependencies' twins and folds the whole closure through them: each
@@ -11,7 +11,7 @@
 //
 // The edges are the NX graph's, not vx's package graph (`^` in vx follows
 // package.json, and an Nx edge from a tsconfig path has no manifest entry),
-// so they are explicit `pkg#nx-input:<name>`. A graph node with no vx
+// so they are explicit `pkg#inputs:<name>`. A graph node with no vx
 // project is transparent: its files join as workspace globs and the walk
 // goes on through it. Nx allows a project cycle and vx's task graph does
 // not: inside a cycle a twin carries its peers' files as workspace globs
@@ -47,8 +47,8 @@ const isFileset = (name: string): boolean =>
 /** A fileset twin is named by its hash: a glob's `*` is no task name. */
 const inputTask = (name: string): string =>
   isFileset(name)
-    ? `nx-input:fileset-${Bun.hash.xxHash3(name).toString(16).padStart(16, '0')}`
-    : `nx-input:${name}`
+    ? `inputs:fileset-${Bun.hash.xxHash3(name).toString(16).padStart(16, '0')}`
+    : `inputs:${name}`
 
 function normRel(p: string): string {
   const s = p.replace(/\/+$/, '')
@@ -63,7 +63,7 @@ export interface NxUpstream {
    * needs, with a transparent node's files added to `into`.
    */
   resolve(node: string, into: NxInputs, todos: string[]): string[]
-  /** Each project's `nx-input:<name>` tasks, for every twin an edge reaches. */
+  /** Each project's `inputs:<name>` tasks, for every twin an edge reaches. */
   inputTasks(): Map<string, GeneratedTask[]>
 }
 

package/src/nx-cache/index.ts

@@ -14,14 +14,12 @@
 import {
   definePlugin,
   type RemoteCacheLayer,
-  type RemoteKey,
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadline } from '../remote-deadline.js'
-import { scopeHeader } from '../remote-scope.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -155,11 +153,10 @@ export class NxRemoteCache implements RemoteCacheLayer {
   private async request(
     method: 'GET' | 'PUT',
     hash: string,
-    at: RemoteKey | undefined,
     body?: Blob,
   ): Promise<Response | undefined> {
     if (this.token === undefined) return undefined
-    const headers: Record<string, string> = scopeHeader(at)
+    const headers: Record<string, string> = {}
     if (this.token !== '') headers['Authorization'] = `Bearer ${this.token}`
     if (body !== undefined) {
       headers['Content-Type'] = 'application/octet-stream'
@@ -212,18 +209,15 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async get(
-    hash: string,
-    at?: RemoteKey,
-  ): Promise<{ body: Response; durationMs: number | undefined } | null> {
-    const res = await this.fetch(hash, at)
+  async get(hash: string): Promise<{ body: Response; durationMs: number | undefined } | null> {
+    const res = await this.fetch(hash)
     // The Nx wire carries no producing-task duration.
     return res === null ? null : { body: res, durationMs: undefined }
   }
 
-  private async fetch(hash: string, at: RemoteKey | undefined): Promise<Response | null> {
+  private async fetch(hash: string): Promise<Response | null> {
     if (this.disabled) return null
-    const res = await this.request('GET', hash, at)
+    const res = await this.request('GET', hash)
     if (res === undefined) return null
     if (res.status !== 200) {
       await res.body?.cancel()
@@ -233,17 +227,18 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async has(hash: string, at?: RemoteKey): Promise<boolean> {
-    const res = await this.fetch(hash, at)
-    if (res === null) return false
+  async has(hash: string): Promise<{ size?: number } | null> {
+    const res = await this.fetch(hash)
+    if (res === null) return null
     await res.body?.cancel()
-    return true
+    const size = Number(res.headers.get('content-length') ?? NaN)
+    return Number.isFinite(size) ? { size } : {}
   }
 
-  // Nx's record carries no duration; only `meta`'s scope is sent.
-  async put(hash: string, body: Blob, meta: { durationMs: number } & RemoteKey): Promise<void> {
+  // Nx's record carries no duration.
+  async put(hash: string, body: Blob): Promise<void> {
     if (this.disabled || this.writesRefused) return
-    const res = await this.request('PUT', hash, meta, body)
+    const res = await this.request('PUT', hash, body)
     if (res === undefined) return
     if (res.status === 200 || res.status === 202 || res.status === 409) return
     throw new Error(`HTTP ${res.status}`)