@vzn/vx-migrate 0.0.645 → 0.0.646

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                                                                                                                                                                                                                                                                       |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.645",
+  "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.645"
+    "@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/shared-outputs.ts

@@ -192,18 +192,24 @@ function cachedOutputs(t: GeneratedTask, index: number): Cached | null {
 }
 
 /**
- * Can the keeper's `ga` give `gb`'s tree back? Only when `ga` is a
- * directory at any depth (`**\/dist`, `**\/dist/**`) and `gb`'s literal
- * head names no such directory: the two meet only at a `dist` nested in
- * `gb`'s tree, which is the sibling's. solid's build outputs `**\/dist`
- * beside types' `types/**`; Turbo caches both, and uncaching types made
- * vx the slower of the two.
+ * Can the keeper's `ga` give `gb`'s tree back? Only when one of the two is
+ * a directory at any depth (`**\/dist`, `**\/dist/**`) and the other's
+ * literal head names no such directory: they meet only where one tree
+ * nests in the other, which neither task writes. solid's build outputs
+ * `dist/**` and `**\/dist` beside types' `types/**` and `**\/types`; Turbo
+ * caches both, and uncaching types made vx the slower of the two.
  */
-function separable(ga: string, gb: string): boolean {
-  const name = /^\*\*\/([^*?[\]{}()!/\\]+)(?:\/\*\*)?$/.exec(ga)?.[1]
+const DIR_ANYWHERE = /^\*\*\/([^*?[\]{}()!/\\]+)(?:\/\*\*)?$/
+
+const separable = (ga: string, gb: string): boolean => apart(ga, gb) || apart(gb, ga)
+
+function apart(dir: string, other: string): boolean {
+  const name = DIR_ANYWHERE.exec(dir)?.[1]
   if (name === undefined) return false
+  const otherName = DIR_ANYWHERE.exec(other)?.[1]
+  if (otherName !== undefined) return otherName !== name
   const head: string[] = []
-  for (const seg of gb.replace(/^(\.\/)+/, '').split('/')) {
+  for (const seg of other.replace(/^(\.\/)+/, '').split('/')) {
     if (!isLiteralPattern(seg) || seg === '') break
     head.push(seg)
   }
@@ -348,7 +354,7 @@ function prefixIndex(): {
 }
 
 /**
- * A keyed group (`cache`, no `exec`: the `nx-input:<name>` twins, Turbo's
+ * A keyed group (`cache`, no `exec`: the `inputs:<name>` twins, Turbo's
  * transit nodes) runs nothing, so core lets its key read what a task
  * writes (`detectInputOverlaps` exempts it). Uncaching one left `{}`, a
  * task core refuses, and every verb failed.

package/src/tracked-outputs.ts

@@ -11,7 +11,7 @@ import { lstat, readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { isLiteralPattern, outputsOverlap } from '@vzn/vx'
 import { relPosix } from './paths.js'
-import { isKeyedGroup, unkey } from './shared-outputs.js'
+import type * as SharedOutputs from './shared-outputs.js'
 
 /** The files git tracks under `root`, root-relative; null outside a repo or without git. */
 export async function trackedFiles(root: string): Promise<string[] | null> {
@@ -135,11 +135,13 @@ export async function headStamp(root: string): Promise<string> {
         const m = /^gitdir: (.*)$/m.exec(await readFile(dotGit, 'utf8').catch(() => ''))
         if (m !== null) gitDir = path.resolve(dir, m[1]!.trim())
       }
-      const head = await readFile(path.join(gitDir, 'HEAD'), 'utf8').catch(() => '')
-      const log = await lstat(path.join(gitDir, 'logs', 'HEAD')).catch(() => null)
-      const index = await lstat(path.join(gitDir, 'index')).catch(() => null)
-      // A worktree's own stack holds its HEAD; the common one, its branches.
-      const common = await readFile(path.join(gitDir, 'commondir'), 'utf8').catch(() => null)
+      const [head, log, index, common] = await Promise.all([
+        readFile(path.join(gitDir, 'HEAD'), 'utf8').catch(() => ''),
+        lstat(path.join(gitDir, 'logs', 'HEAD')).catch(() => null),
+        lstat(path.join(gitDir, 'index')).catch(() => null),
+        // A worktree's own stack holds its HEAD; the common one, its branches.
+        readFile(path.join(gitDir, 'commondir'), 'utf8').catch(() => null),
+      ])
       const tables = await Promise.all(
         [gitDir, ...(common === null ? [] : [path.resolve(gitDir, common.trim())])].map((d) =>
           readFile(path.join(d, 'reftable', 'tables.list'), 'utf8').catch(() => ''),
@@ -236,6 +238,8 @@ export function spareTrackedOutputs(
   }[],
   tracked: readonly string[],
 ): [string, string][] {
+  // Loaded here, on a remap only: a kept mapping's run never reads it.
+  const { isKeyedGroup, unkey } = require('./shared-outputs.js') as typeof SharedOutputs
   const todos: [string, string][] = []
   const trackedSet = new Set(tracked)
   /** Drop the `!` entries readers carry for a committed file no output names any more. */

package/src/turbo/index.ts

@@ -21,14 +21,14 @@ import { collectGaps } from '../plugin-gaps.js'
 import { gitIgnored, trackedKinds } from '../tracked-outputs.js'
 import { packageScripts, relPosix } from '../paths.js'
 import { onceReader, type ReadText, tscBuildInfo } from '../tsc-buildinfo.js'
+import type * as TurboMap from './turbo-map.js'
+import type { TurboMappedProject } from './turbo-map.js'
 import {
   envNamesThatMap,
-  mapTurboWorkspace,
   microfrontendsConfigs,
   rootTaskProject,
   turboConfigFile,
-  type TurboMappedProject,
-} from './turbo-map.js'
+} from './turbo-reads.js'
 
 /** The note every persistent task carries; like every gap, reported once per run for all its tasks. */
 const PERSISTENT_NOTE =
@@ -192,11 +192,15 @@ const textOf = (file: string): Promise<string> =>
  * `.yarnrc.yml` and the microfrontends configs.
  */
 async function run(root: string, projects: readonly ProjectMeta[]): Promise<AdoptionRun> {
-  const metas = await withManifests(projects)
-  const dirs = [root, ...metas.map((m) => m.dir)]
-  const configs = await Promise.all(
-    dirs.flatMap((d) => ['turbo.json', 'turbo.jsonc'].map((f) => textOf(path.join(d, f)))),
-  )
+  const dirs = [root, ...projects.map((m) => m.dir)]
+  const [metas, configs, yarnrc, rootManifest] = await Promise.all([
+    withManifests(projects),
+    Promise.all(
+      dirs.flatMap((d) => ['turbo.json', 'turbo.jsonc'].map((f) => textOf(path.join(d, f)))),
+    ),
+    textOf(path.join(root, '.yarnrc.yml')),
+    textOf(path.join(root, 'package.json')),
+  ])
   const envNames = envNamesThatMap(configs, envNamesNow())
   // The tsconfigs a `tsc` script reads are the mapping's inputs too.
   const tsc = onceReader()
@@ -213,9 +217,9 @@ async function run(root: string, projects: readonly ProjectMeta[]): Promise<Adop
       process.env['TURBO_CI_VENDOR_ENV_KEY'] ?? '',
       process.env['TURBO_ENV_MODE'] ?? '',
       ...configs,
-      await textOf(path.join(root, '.yarnrc.yml')),
+      yarnrc,
       // Its dependencies are global inputs, a member or not.
-      await textOf(path.join(root, 'package.json')),
+      rootManifest,
       JSON.stringify(microfrontendsConfigs(root, dirs)),
       // A config file added beside mapped tasks changes what an output may cover.
       JSON.stringify(metas.map((m) => [m.name, m.dir, m.packageJson, m.configPath])),
@@ -244,6 +248,8 @@ async function mapAll(
       m.configPath === null ? [] : [[relPosix(root, m.dir), path.basename(m.configPath)] as const],
     ),
   )
+  // Only a mapping the kept one no longer holds loads the mapper.
+  const { mapTurboWorkspace } = require('./turbo-map.js') as typeof TurboMap
   const mapped = await mapTurboWorkspace(root, metas, {
     // Inline: the values themselves, where `bunx @vzn/vx-migrate` splices a preset import.
     splice: (_kind, values) => values,

package/src/turbo/turbo-map.ts

@@ -10,7 +10,6 @@
 //     written.
 // The consumer decides what a global becomes through `splice`.
 
-import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { isLiteralPattern, pruneOrphanPersistentNotes, UserError } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
@@ -31,6 +30,13 @@ import {
 } from '../shared-outputs.js'
 import { manifestGraph, type ManifestGraph } from '../manifest-graph.js'
 import { isRecord, packageScripts, relPosix } from '../paths.js'
+import {
+  FRAMEWORK_ENV,
+  keyable,
+  microfrontendsConfigs,
+  ROOT,
+  turboConfigFile,
+} from './turbo-reads.js'
 import type { TrackedKinds } from '../tracked-outputs.js'
 import {
   DOTENV_PROBE,
@@ -69,34 +75,6 @@ interface TurboJson {
 
 const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 
-/** A name core takes in `inputs.env` and `exec.env.passThrough`. */
-const keyable = (name: string): boolean =>
-  name.length > 0 && !name.startsWith('!') && !/[*?[\]{}=\0]/.test(name)
-
-/**
- * The names of `names` a live mapping can read differently: each a `*` in
- * one of `configs` (turbo.json texts, any string, a superset) or in Turbo's
- * framework table matches, and each core cannot key (a literal one is
- * dropped only when no variable has it). The kept mapping keyed on every
- * name, so any variable that came or went (a CI step's, `VX_DEBUG_TIMING`)
- * remapped the workspace: ~330 ms a run on vercel/ai.
- */
-export function envNamesThatMap(configs: readonly string[], names: readonly string[]): string[] {
-  const patterns = new Set(FRAMEWORK_ENV.flatMap((f) => f.env).filter((e) => e.includes('*')))
-  for (const text of configs)
-    for (const m of text.matchAll(/"((?:[^"\\]|\\.)*)"/g))
-      if (m[1]!.includes('*')) patterns.add(m[1]!)
-  // Backslashes and a leading `!` dropped, every `*` a wildcard: wider
-  // than Turbo's reading, never narrower.
-  const res = [...patterns].map(
-    (p) =>
-      new RegExp(
-        `^${p.replaceAll('\\', '').replace(/^!/, '').split('*').map(RegExp.escape).join('.*')}$`,
-      ),
-  )
-  return names.filter((n) => !keyable(n) || res.some((re) => re.test(n)))
-}
-
 /**
  * A Turbo env list's explicit names, read as Turbo reads them
  * (`wildcard_to_regex_pattern`): `*` is the one wildcard, `\*` a
@@ -195,83 +173,6 @@ const KNOWN_TASK_KEYS = new Set([
 const OUTPUT_LOGS_DEFAULT = 'new-only'
 const OUTPUT_LOGS_RUN_FLAG = new Set(['full', 'hash-only', 'errors-only', 'none'])
 
-// Turbo 2's framework inference: a package that depends on a framework
-// has its variables hashed into its tasks and passed to them, with
-// nothing in turbo.json saying so. vx env names are explicit, so the
-// variables were stripped in silence and a build that inlines them
-// (Next's `NEXT_PUBLIC_*`) read empty values (item 940). A live mapping
-// (`envNames`) infers them as Turbo does; the migrate CLI lists the names
-// the package's own files spell (`sourceNames`) and says so in a note.
-// Turbo's own table (`packages/turbo-types/src/json/frameworks.json`),
-// in its order: a package takes the FIRST framework it matches, `all`
-// needing every dependency and `some` any one.
-const NITRO_ENV = [
-  'NITRO_*',
-  'SERVER_*',
-  'AWS_APP_ID',
-  'INPUT_AZURE_STATIC_WEB_APPS_API_TOKEN',
-  'CLEAVR',
-  'CF_PAGES',
-  'FIREBASE_APP_HOSTING',
-  'NETLIFY',
-  'STORMKIT',
-  'NOW_BUILDER',
-  'ZEABUR',
-  'RENDER',
-]
-const FRAMEWORK_ENV: ReadonlyArray<{
-  slug: string
-  env: readonly string[]
-  all: boolean
-  dependencies: readonly string[]
-}> = [
-  { slug: 'astro', env: ['PUBLIC_*'], all: true, dependencies: ['astro'] },
-  { slug: 'blitzjs', env: ['NEXT_PUBLIC_*'], all: true, dependencies: ['blitz'] },
-  {
-    slug: 'create-react-app',
-    env: ['REACT_APP_*'],
-    all: false,
-    dependencies: ['react-scripts', 'react-dev-utils'],
-  },
-  { slug: 'expo', env: ['EXPO_PUBLIC_*'], all: true, dependencies: ['expo'] },
-  { slug: 'gatsby', env: ['GATSBY_*'], all: true, dependencies: ['gatsby'] },
-  {
-    slug: 'nextjs',
-    env: ['NEXT_PUBLIC_*', 'NEXT_DEPLOYMENT_ID'],
-    all: true,
-    dependencies: ['next'],
-  },
-  {
-    slug: 'nitro',
-    env: NITRO_ENV,
-    all: false,
-    dependencies: ['nitropack', 'nitropack-nightly', 'nitro', 'nitro-nightly'],
-  },
-  {
-    slug: 'nuxtjs',
-    env: ['NUXT_*', 'NUXT_ENV_*', ...NITRO_ENV, 'LAUNCH_EDITOR'],
-    all: false,
-    dependencies: ['nuxt', 'nuxt-edge', 'nuxt3', 'nuxt3-edge'],
-  },
-  { slug: 'redwoodjs', env: ['REDWOOD_ENV_*'], all: true, dependencies: ['@redwoodjs/core'] },
-  {
-    slug: 'remix',
-    env: ['REMIX_*'],
-    all: false,
-    dependencies: ['@remix-run/dev', '@remix-run/react', '@remix-run/serve', '@react-router/dev'],
-  },
-  { slug: 'sanity', env: ['SANITY_STUDIO_*'], all: true, dependencies: ['@sanity/cli'] },
-  { slug: 'solidstart', env: ['VITE_*'], all: true, dependencies: ['solid-js', 'solid-start'] },
-  { slug: 'sveltekit', env: ['VITE_*', 'PUBLIC_*'], all: true, dependencies: ['@sveltejs/kit'] },
-  { slug: 'vite', env: ['VITE_*'], all: true, dependencies: ['vite'] },
-  {
-    slug: 'vue',
-    env: ['VUE_APP_*', 'LAUNCH_EDITOR'],
-    all: true,
-    dependencies: ['@vue/cli-service'],
-  },
-]
-
 /** The three global fields of turbo.json a task may draw on. */
 export type TurboGlobal = 'inputs' | 'env' | 'pass'
 
@@ -424,45 +325,6 @@ function keyIgnored(
   inputs.workspaceRuntime = [...probes, ignoredFilesProbe(hits.map(([rel]) => rel))]
 }
 
-/**
- * A directory's Turbo config: `turbo.json`, else `turbo.jsonc` (Turbo 2.5+
- * reads either). Only `turbo.json` was looked for, so a `turbo.jsonc` root
- * failed the run with ENOENT and a package's `turbo.jsonc` overlay was
- * skipped in silence — its `inputs` then keyed nothing (item 938).
- */
-export async function turboConfigFile(dir: string): Promise<string | null> {
-  for (const name of ['turbo.json', 'turbo.jsonc']) {
-    const file = path.join(dir, name)
-    if (await Bun.file(file).exists()) return file
-  }
-  return null
-}
-
-/**
- * The workspace root as a project to name when turbo.json declares `//#`
- * tasks: its package name and directory. Null with no such task, a
- * nameless root, or a file the mapping refuses (it names the file).
- */
-export async function rootTaskProject(root: string): Promise<{ name: string; dir: string } | null> {
-  const file = await turboConfigFile(root)
-  if (file === null) return null
-  let turbo: { tasks?: unknown; pipeline?: unknown } | null
-  let pkg: { name?: unknown } | null
-  try {
-    turbo = Bun.JSONC.parse(await Bun.file(file).text()) as typeof turbo
-    pkg = (await Bun.file(path.join(root, 'package.json')).json()) as typeof pkg
-  } catch {
-    return null
-  }
-  const tasks = turbo?.tasks ?? turbo?.pipeline
-  const hasRootTask =
-    typeof tasks === 'object' &&
-    tasks !== null &&
-    Object.keys(tasks).some((k) => k.startsWith(`${ROOT}#`))
-  if (!hasRootTask || typeof pkg?.name !== 'string' || pkg.name === '') return null
-  return { name: pkg.name, dir: root }
-}
-
 async function readTurboJson(file: string, root: string): Promise<TurboJson> {
   const text = await Bun.file(file).text()
   let parsed: unknown
@@ -606,7 +468,6 @@ function badCommand(def: TurboTask): boolean {
 
 /** Declared task names for a package: plain root keys, `pkg#name` keys
  * for this package, and per-package turbo.json keys — in that order. */
-const ROOT = '//'
 
 /**
  * A package's turbo.json files, root first and its own last, as Turbo's
@@ -892,36 +753,6 @@ async function rootPackageJson(root: string): Promise<PackageMeta['packageJson']
   return (pkg !== null && typeof pkg === 'object' ? pkg : {}) as PackageMeta['packageJson']
 }
 
-/**
- * The microfrontends configs Turbo hashes into every task: each package's
- * (the root's too) `microfrontends.json`, else `microfrontends.jsonc`, or
- * the one name `VC_MICROFRONTENDS_CONFIG_FILE_NAME` gives, unless it is a
- * child's `{ "partOf": … }` (Turbo's `update_turbo_json` appends them to
- * the root's global deps). Unread, an edit to `web`'s routes replayed every
- * sibling app's build (with-microfrontends, Turbo 2.11's dry run moves all
- * 18 tasks). Paths are root-relative; `text` is what the mapping read.
- */
-export function microfrontendsConfigs(
-  root: string,
-  dirs: readonly string[],
-  custom = process.env['VC_MICROFRONTENDS_CONFIG_FILE_NAME'] ?? '',
-): { rel: string; text: string }[] {
-  const names = custom === '' ? ['microfrontends.json', 'microfrontends.jsonc'] : [custom]
-  const out: { rel: string; text: string }[] = []
-  for (const dir of new Set(dirs.map((d) => path.resolve(d)))) {
-    const file = names.map((n) => path.join(dir, n)).find((f) => existsSync(f))
-    if (file === undefined) continue
-    const text = readFileSync(file, 'utf8')
-    let child = false
-    try {
-      const parsed = Bun.JSONC.parse(text) as { partOf?: unknown } | null
-      child = typeof parsed?.partOf === 'string'
-    } catch {}
-    if (!child) out.push({ rel: relPosix(root, file), text })
-  }
-  return out.sort((a, b) => (a.rel < b.rel ? -1 : 1))
-}
-
 export async function mapTurboWorkspace(
   root: string,
   metas: readonly PackageMeta[],
@@ -1177,7 +1008,7 @@ export async function mapTurboWorkspace(
   // over its files, so `test` keys on its dependencies' sources. Dropped,
   // vx keyed `test` on its own files alone: a dependency's edit was a hit.
   // Each package has it as a key-only task, a keyed group, as nx()'s
-  // `nx-input:*` twins are.
+  // `inputs:*` twins are.
   const withScript = new Set<string>()
   for (const set of runnable.values()) for (const name of set) withScript.add(name)
   const sameRefs = new Set<string>()

package/src/turbo/turbo-reads.ts

@@ -0,0 +1,183 @@
+// What a turbo() run reads before it knows whether its kept mapping still
+// holds: the mapping itself (`turbo-map.ts`, ~240 KB with what it imports)
+// loads only when it does not.
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { relPosix } from '../paths.js'
+
+/** Turbo's name for the workspace root in `//#task` and `extends`. */
+export const ROOT = '//'
+
+// Turbo 2's framework inference: a package that depends on a framework
+// has its variables hashed into its tasks and passed to them, with
+// nothing in turbo.json saying so. vx env names are explicit, so the
+// variables were stripped in silence and a build that inlines them
+// (Next's `NEXT_PUBLIC_*`) read empty values (item 940). A live mapping
+// (`envNames`) infers them as Turbo does; the migrate CLI lists the names
+// the package's own files spell (`sourceNames`) and says so in a note.
+// Turbo's own table (`packages/turbo-types/src/json/frameworks.json`),
+// in its order: a package takes the FIRST framework it matches, `all`
+// needing every dependency and `some` any one.
+const NITRO_ENV = [
+  'NITRO_*',
+  'SERVER_*',
+  'AWS_APP_ID',
+  'INPUT_AZURE_STATIC_WEB_APPS_API_TOKEN',
+  'CLEAVR',
+  'CF_PAGES',
+  'FIREBASE_APP_HOSTING',
+  'NETLIFY',
+  'STORMKIT',
+  'NOW_BUILDER',
+  'ZEABUR',
+  'RENDER',
+]
+export const FRAMEWORK_ENV: ReadonlyArray<{
+  slug: string
+  env: readonly string[]
+  all: boolean
+  dependencies: readonly string[]
+}> = [
+  { slug: 'astro', env: ['PUBLIC_*'], all: true, dependencies: ['astro'] },
+  { slug: 'blitzjs', env: ['NEXT_PUBLIC_*'], all: true, dependencies: ['blitz'] },
+  {
+    slug: 'create-react-app',
+    env: ['REACT_APP_*'],
+    all: false,
+    dependencies: ['react-scripts', 'react-dev-utils'],
+  },
+  { slug: 'expo', env: ['EXPO_PUBLIC_*'], all: true, dependencies: ['expo'] },
+  { slug: 'gatsby', env: ['GATSBY_*'], all: true, dependencies: ['gatsby'] },
+  {
+    slug: 'nextjs',
+    env: ['NEXT_PUBLIC_*', 'NEXT_DEPLOYMENT_ID'],
+    all: true,
+    dependencies: ['next'],
+  },
+  {
+    slug: 'nitro',
+    env: NITRO_ENV,
+    all: false,
+    dependencies: ['nitropack', 'nitropack-nightly', 'nitro', 'nitro-nightly'],
+  },
+  {
+    slug: 'nuxtjs',
+    env: ['NUXT_*', 'NUXT_ENV_*', ...NITRO_ENV, 'LAUNCH_EDITOR'],
+    all: false,
+    dependencies: ['nuxt', 'nuxt-edge', 'nuxt3', 'nuxt3-edge'],
+  },
+  { slug: 'redwoodjs', env: ['REDWOOD_ENV_*'], all: true, dependencies: ['@redwoodjs/core'] },
+  {
+    slug: 'remix',
+    env: ['REMIX_*'],
+    all: false,
+    dependencies: ['@remix-run/dev', '@remix-run/react', '@remix-run/serve', '@react-router/dev'],
+  },
+  { slug: 'sanity', env: ['SANITY_STUDIO_*'], all: true, dependencies: ['@sanity/cli'] },
+  { slug: 'solidstart', env: ['VITE_*'], all: true, dependencies: ['solid-js', 'solid-start'] },
+  { slug: 'sveltekit', env: ['VITE_*', 'PUBLIC_*'], all: true, dependencies: ['@sveltejs/kit'] },
+  { slug: 'vite', env: ['VITE_*'], all: true, dependencies: ['vite'] },
+  {
+    slug: 'vue',
+    env: ['VUE_APP_*', 'LAUNCH_EDITOR'],
+    all: true,
+    dependencies: ['@vue/cli-service'],
+  },
+]
+
+/** A name core takes in `inputs.env` and `exec.env.passThrough`. */
+export const keyable = (name: string): boolean =>
+  name.length > 0 && !name.startsWith('!') && !/[*?[\]{}=\0]/.test(name)
+
+/**
+ * The names of `names` a live mapping can read differently: each a `*` in
+ * one of `configs` (turbo.json texts, any string, a superset) or in Turbo's
+ * framework table matches, and each core cannot key (a literal one is
+ * dropped only when no variable has it). The kept mapping keyed on every
+ * name, so any variable that came or went (a CI step's, `VX_DEBUG_TIMING`)
+ * remapped the workspace: ~330 ms a run on vercel/ai.
+ */
+export function envNamesThatMap(configs: readonly string[], names: readonly string[]): string[] {
+  const patterns = new Set(FRAMEWORK_ENV.flatMap((f) => f.env).filter((e) => e.includes('*')))
+  for (const text of configs)
+    for (const m of text.matchAll(/"((?:[^"\\]|\\.)*)"/g))
+      if (m[1]!.includes('*')) patterns.add(m[1]!)
+  // Backslashes and a leading `!` dropped, every `*` a wildcard: wider
+  // than Turbo's reading, never narrower.
+  const res = [...patterns].map(
+    (p) =>
+      new RegExp(
+        `^${p.replaceAll('\\', '').replace(/^!/, '').split('*').map(RegExp.escape).join('.*')}$`,
+      ),
+  )
+  return names.filter((n) => !keyable(n) || res.some((re) => re.test(n)))
+}
+
+/**
+ * A directory's Turbo config: `turbo.json`, else `turbo.jsonc` (Turbo 2.5+
+ * reads either). Only `turbo.json` was looked for, so a `turbo.jsonc` root
+ * failed the run with ENOENT and a package's `turbo.jsonc` overlay was
+ * skipped in silence — its `inputs` then keyed nothing (item 938).
+ */
+export async function turboConfigFile(dir: string): Promise<string | null> {
+  for (const name of ['turbo.json', 'turbo.jsonc']) {
+    const file = path.join(dir, name)
+    if (await Bun.file(file).exists()) return file
+  }
+  return null
+}
+
+/**
+ * The workspace root as a project to name when turbo.json declares `//#`
+ * tasks: its package name and directory. Null with no such task, a
+ * nameless root, or a file the mapping refuses (it names the file).
+ */
+export async function rootTaskProject(root: string): Promise<{ name: string; dir: string } | null> {
+  const file = await turboConfigFile(root)
+  if (file === null) return null
+  let turbo: { tasks?: unknown; pipeline?: unknown } | null
+  let pkg: { name?: unknown } | null
+  try {
+    turbo = Bun.JSONC.parse(await Bun.file(file).text()) as typeof turbo
+    pkg = (await Bun.file(path.join(root, 'package.json')).json()) as typeof pkg
+  } catch {
+    return null
+  }
+  const tasks = turbo?.tasks ?? turbo?.pipeline
+  const hasRootTask =
+    typeof tasks === 'object' &&
+    tasks !== null &&
+    Object.keys(tasks).some((k) => k.startsWith(`${ROOT}#`))
+  if (!hasRootTask || typeof pkg?.name !== 'string' || pkg.name === '') return null
+  return { name: pkg.name, dir: root }
+}
+
+/**
+ * The microfrontends configs Turbo hashes into every task: each package's
+ * (the root's too) `microfrontends.json`, else `microfrontends.jsonc`, or
+ * the one name `VC_MICROFRONTENDS_CONFIG_FILE_NAME` gives, unless it is a
+ * child's `{ "partOf": … }` (Turbo's `update_turbo_json` appends them to
+ * the root's global deps). Unread, an edit to `web`'s routes replayed every
+ * sibling app's build (with-microfrontends, Turbo 2.11's dry run moves all
+ * 18 tasks). Paths are root-relative; `text` is what the mapping read.
+ */
+export function microfrontendsConfigs(
+  root: string,
+  dirs: readonly string[],
+  custom = process.env['VC_MICROFRONTENDS_CONFIG_FILE_NAME'] ?? '',
+): { rel: string; text: string }[] {
+  const names = custom === '' ? ['microfrontends.json', 'microfrontends.jsonc'] : [custom]
+  const out: { rel: string; text: string }[] = []
+  for (const dir of new Set(dirs.map((d) => path.resolve(d)))) {
+    const file = names.map((n) => path.join(dir, n)).find((f) => existsSync(f))
+    if (file === undefined) continue
+    const text = readFileSync(file, 'utf8')
+    let child = false
+    try {
+      const parsed = Bun.JSONC.parse(text) as { partOf?: unknown } | null
+      child = typeof parsed?.partOf === 'string'
+    } catch {}
+    if (!child) out.push({ rel: relPosix(root, file), text })
+  }
+  return out.sort((a, b) => (a.rel < b.rel ? -1 : 1))
+}

package/src/turbo-cache/index.ts

@@ -18,6 +18,7 @@ import path from 'node:path'
 import {
   type ArtifactInfo,
   definePlugin,
+  type LentAccess,
   type RemoteCacheLayer,
   type RemoteOpenContext,
   type VxPlugin,
@@ -428,6 +429,9 @@ async function boundedText(res: Response, max: number): Promise<string | null> {
  */
 const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
 
+/** A lent token ending sooner than this is exchanged again first, so an agent's request never carries a spent one. */
+const LEND_MARGIN_MS = 5 * 60_000
+
 /**
  * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
  * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
@@ -464,8 +468,14 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private token: string | undefined
   /** Set by `open` when the token came from the keychain: a refusal deletes it. */
   private forget: (() => Promise<void>) | undefined
-  /** The token an OIDC exchange gave, revoked when the run ends. */
-  private exchanged: string | undefined
+  /** The tokens OIDC exchanges gave, the last one current, each revoked when the run ends. */
+  private exchanged: string[] = []
+  /** When the current exchanged token ends (epoch ms), when the server said. */
+  private expiresAt: number | undefined
+  /** Set by `open` when this machine has a lent token and no token of its own: read per request. */
+  private borrowed: (() => string | undefined) | undefined
+  /** The token a run running its tasks here lent (`CacheContext.lent`). */
+  lent: (() => string | undefined) | undefined
   private readonly keychainRemote: KeychainRemote
   /** The remote's rate limit, which every request of this client waits out. */
   private readonly cooldown = new Cooldown()
@@ -491,26 +501,59 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   }
 
   async open(ctx: RemoteOpenContext): Promise<void> {
-    if (this.config.oidcMissing)
+    const lent = this.lent?.() === undefined ? undefined : this.lent
+    if (this.config.oidcMissing && lent === undefined)
       ctx.warn(
         'oidc: GitHub gave this job no OIDC token: it needs `permissions: id-token: write` (a fork or Dependabot pull request never gets one)',
       )
     if (this.token !== undefined) return
+    // A lent token beats this machine's own OIDC: the server files a write
+    // by the token, so an agent's own (another workflow, another ref)
+    // filed the task where its run could not read it.
+    if (lent !== undefined) {
+      this.borrowed = lent
+      return
+    }
     if (this.config.oidc !== undefined) {
       try {
-        this.token = await exchangeOidc(this.config.oidc, this.fetchImpl, this.wait)
+        await this.exchange()
       } catch (err) {
         throw new Error(
           `oidc: ${err instanceof Error ? err.message : String(err)}; local cache only this run`,
         )
       }
-      this.exchanged = this.token
       return
     }
     this.token = await keychainToken(ctx, this.keychainRemote)
     this.forget = () => ctx.forgetSecret({ key: this.keychainRemote.key })
   }
 
+  private async exchange(): Promise<void> {
+    const got = await exchangeOidc(this.config.oidc!, this.fetchImpl, this.wait)
+    this.token = got.token
+    this.expiresAt = got.expiresAt
+    this.exchanged.push(got.token)
+  }
+
+  /**
+   * The token an OIDC exchange gave this run, for a machine that runs its
+   * tasks (`RemoteCacheLayer.lend`); exchanged again when it ends within
+   * five minutes. A token of any other kind is never lent.
+   */
+  async lend(): Promise<LentAccess | undefined> {
+    if (this.exchanged.length === 0) return undefined
+    if (this.expiresAt !== undefined && this.expiresAt - Date.now() < LEND_MARGIN_MS)
+      await this.exchange()
+    return {
+      token: this.token!,
+      ...(this.expiresAt === undefined ? {} : { expiresAt: this.expiresAt }),
+    }
+  }
+
+  private bearer(): string | undefined {
+    return this.borrowed?.() ?? this.token
+  }
+
   private url(pathname: string): string {
     const u = new URL(`${this.config.apiUrl}/v8/artifacts${pathname}`)
     // Turbo sends a team id only in Vercel's `team_` form (its API client's
@@ -523,7 +566,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
   private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      ...(auth ? { Authorization: `Bearer ${this.token}` } : {}),
+      ...(auth ? { Authorization: `Bearer ${this.bearer()}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
@@ -550,7 +593,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     const res = await this.fetchImpl(url, {
       method: 'OPTIONS',
       headers: {
-        Authorization: `Bearer ${this.token}`,
+        Authorization: `Bearer ${this.bearer()}`,
         'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
         'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
       },
@@ -579,7 +622,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     pathname: string,
     init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
   ): Promise<Response | undefined> {
-    if (this.token === undefined) return undefined
+    if (this.bearer() === undefined) return undefined
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
     // 0 is Turbo's "no deadline".
     const signal = () => (timeoutMs === 0 ? undefined : deadline(timeoutMs))
@@ -629,12 +672,11 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  /** Revoke the token `open` exchanged, once; a throw is the caller's warning. */
+  /** Revoke each token this run exchanged, once; a throw is the caller's warning. */
   async revoke(): Promise<void> {
-    const token = this.exchanged
-    if (token === undefined) return
-    this.exchanged = undefined
-    await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
+    const tokens = this.exchanged.splice(0)
+    for (const token of tokens)
+      await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
   }
 
   async has(hash: string): Promise<ArtifactInfo | null> {
@@ -859,6 +901,7 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
       // sandboxed task may read (L-45).
       const layer = new TurboRemoteCache(config, fetch, ctx.cacheDir)
       layer.reads = readScopes(ctx.refs)
+      layer.lent = ctx.lent
       if (config.oidc !== undefined) opened = { layer, warn: ctx.warn }
       return scope === 'key' ? keyedByRef(layer, ctx.refs) : layer
     },

package/src/turbo-cache/oidc.ts

@@ -111,12 +111,18 @@ async function field(res: Response, name: string, what: string): Promise<string>
   return value
 }
 
+/** An exchanged token, and when it ends (epoch ms) when the server says. */
+export interface Exchanged {
+  readonly token: string
+  readonly expiresAt?: number
+}
+
 /** The job's OIDC token, exchanged for the cache's access token. Errors never quote a token. */
 export async function exchangeOidc(
   cfg: OidcConfig,
   fetchImpl: typeof fetch = fetch,
   wait: (ms: number) => Promise<void> = Bun.sleep,
-): Promise<string> {
+): Promise<Exchanged> {
   const idUrl = new URL(cfg.idTokenUrl)
   if (cfg.audience !== undefined) idUrl.searchParams.set('audience', cfg.audience)
   const idToken = await field(
@@ -129,22 +135,31 @@ export async function exchangeOidc(
     'value',
     `GitHub's OIDC endpoint (${where(cfg.idTokenUrl)})`,
   )
-  return field(
-    await send(
-      fetchImpl,
-      cfg.tokenUrl,
-      form({
-        grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
-        subject_token: idToken,
-        subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
-        requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
-        ...cfg.params,
-      }),
-      wait,
-    ),
-    'access_token',
-    `the token exchange (${where(cfg.tokenUrl)})`,
+  const res = await send(
+    fetchImpl,
+    cfg.tokenUrl,
+    form({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      subject_token: idToken,
+      subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+      requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
+      ...cfg.params,
+    }),
+    wait,
   )
+  const what = `the token exchange (${where(cfg.tokenUrl)})`
+  if (!res.ok) {
+    await res.body?.cancel()
+    throw new Error(`${what} answered HTTP ${res.status}`)
+  }
+  const body = (await res.json().catch(() => null)) as Record<string, unknown> | null
+  const token = body?.['access_token']
+  if (typeof token !== 'string' || token === '') throw new Error(`${what} sent no access_token`)
+  const ttl = body?.['expires_in']
+  return {
+    token,
+    ...(typeof ttl === 'number' && ttl > 0 ? { expiresAt: Date.now() + ttl * 1000 } : {}),
+  }
 }
 
 /** Revoke the exchanged token; a throw is the caller's warning. */