@vzn/vx-migrate 0.0.650 → 0.0.651

package/README.md

@@ -30,7 +30,7 @@ The package exports `turbo`, `nx`, `turboCache`, `nxCache` and their options typ
 
 ## `turbo()` — a Turbo repo, mid-migration
 
-Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every package's `build` script the way `turbo run build` would: `dependsOn` edges (`^build`, same-package deps, `pkg#task`), `inputs` as every task's key and `outputs` as the cache block, `env` / `passThroughEnv`, `cache: false`, `persistent`. Turbo's global fields (`globalDependencies`, `globalEnv`, `globalPassThroughEnv`, Turbo 1's `globalDotEnv`) are inlined into every task; a `*` env name (`NEXT_PUBLIC_*`) expands over the run's environment, as Turbo matches it; `*` is Turbo's only wildcard (`\*`, a leading `\!`, `?` and `[` are literal), and a literal vx cannot key (unkey's `NEXT_PUBLIC_\*`) is left out, reported once only when the run's environment sets it; per-package `turbo.json` overlays apply. A `turbo.jsonc` (Turbo 2.5+) is read wherever a `turbo.json` would be, at the root and in a package; a workspace root with neither is refused, naming the fix. Turbo 2's framework inference (a package on `next` has `NEXT_PUBLIC_*` and `NEXT_DEPLOYMENT_ID` hashed and passed; Turbo's whole table, `expo`, `nuxt`, `remix`, `@sveltejs/kit` and the rest, each package taking the first framework it matches, as Turbo does, and leaving out names under the platform's `TURBO_CI_VENDOR_ENV_KEY`) applies too: the prefix expands over the run's environment into that package's tasks, and a task's `!` entry takes names back (`bunx @vzn/vx-migrate`, which writes files for another environment, names each framework and its packages in a note instead). What runs is what a migration would have written, minus the file: the key a task derives here equals the key the written config would derive.
+Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps every package's `build` script the way `turbo run build` would: `dependsOn` edges (`^build`, same-package deps, `pkg#task`), `inputs` as every task's key and `outputs` as the cache block, `env` / `passThroughEnv`, `cache: false`, `persistent`. Turbo's global fields (`globalDependencies`, `globalEnv`, `globalPassThroughEnv`, Turbo 1's `globalDotEnv`) are inlined into every task; a `*` env name (`NEXT_PUBLIC_*`) expands over the run's environment, as Turbo matches it; `*` is Turbo's only wildcard (`\*`, a leading `\!`, `?` and `[` are literal), and a literal vx cannot key (unkey's `NEXT_PUBLIC_\*`) is left out, reported once only when the run's environment sets it; per-package `turbo.json` overlays apply. A `turbo.jsonc` (Turbo 2.5+) is read wherever a `turbo.json` would be, at the root and in a package; a directory holding both is refused, as Turbo refuses it, and a workspace root with neither is refused, naming the fix. An absolute path in `inputs`, `outputs`, `globalDependencies` or `global.inputs` is refused naming the file, as Turbo refuses it. Turbo 2's framework inference (a package on `next` has `NEXT_PUBLIC_*` and `NEXT_DEPLOYMENT_ID` hashed and passed; Turbo's whole table, `expo`, `nuxt`, `remix`, `@sveltejs/kit` and the rest, each package taking the first framework it matches, as Turbo does, and leaving out names under the platform's `TURBO_CI_VENDOR_ENV_KEY`) applies too: the prefix expands over the run's environment into that package's tasks, and a task's `!` entry takes names back (`bunx @vzn/vx-migrate`, which writes files for another environment, names each framework and its packages in a note instead). Turbo's builtin env applies as Turbo's source has it: `VERCEL_ANALYTICS_ID` and `VERCEL_TARGET_ENV` are keyed in every task (a `globalEnv` `!` entry such as `!VERCEL*` takes them back), Next's skew rule keys `VERCEL_DEPLOYMENT_ID` when `VERCEL_SKEW_PROTECTION_ENABLED=1`, and the literal names of Turbo's builtin pass-through list (`TZ`, `HOME`, `CI`, the Vercel, Docker and IDE names) reach every task unkeyed. Its wildcard families (`VERCEL_*`, `GITHUB_*`, `DOCKER_*` and the rest) are not matched against the run's environment: `exec.env.passThrough` is keyed by name, so a live match keyed each machine apart. The written config keys the defaults and `VERCEL_DEPLOYMENT_ID` always (a miss where Turbo would hit, never a stale hit) and passes the same literal names from the preset; a note names the wildcard families to add where a task reads them. What runs is what a migration would have written, minus the file: the key a task derives here equals the key the written config would derive.
 
 | Option | Meaning                                                                                                     |
 | ------ | ----------------------------------------------------------------------------------------------------------- |
@@ -74,12 +74,17 @@ Rules:
 - A task's `description` (Turbo 2.11.5's schema) is the vx task's `description`.
 - `outputLogs: "new-only"` maps to nothing: frames for the tasks that ran and a one-liner per cache hit is vx's default flow already. The other values are per-run in vx, so they are a todo naming the flag (`vx run … --output-logs hash-only`).
 - `interruptible` maps to nothing: `vx watch` keeps a persistent task up across cycles and restarts it only when its config changes or it dies.
-- A task's `tags` (Turbo main, after 2.11.5) map to nothing: Turbo keeps them out of the hash and the run.
+- A package's own turbo.json `tags` (Turbo 2.11.6) are its vx project `tags`, so `vx run build --filter tag:ci` selects what `turbo run build --filter=tag:ci` does through package tags (the root's label the root project, none inherited, as in Turbo). A task's `tags` map to nothing: vx tags are a project's, so a `tag:` filter never reaches a task by its own tags.
+- A task's `experimentalCI` maps to nothing: Turbo reads it for external CI tooling and acts on nothing.
 - `envMode: "loose"` (top-level or in `global`, or `TURBO_ENV_MODE=loose`, which wins) is a note: Turbo hands every task the whole environment, vx only the declared names.
 - The workspace keys vx has a home for, top level or in `global`, fill what `.vx/workspace.ts` leaves unset: `run.concurrency` (`"10"`, `"50%"` of the cores) → `run.concurrency`. `TURBO_CONCURRENCY` wins over turbo.json, as under Turbo; a set one decides, its `0` included. `cacheMaxSize` / `cacheMaxAge` map to nothing: no vx run evicts, `vx cache clean --max-size / --older-than` does.
-- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is the run's base commit (`setBranch({ base })`): a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`.
+- `TURBO_FORCE=true` (or `1`), `turbo run --force`, turns every cache read off through the workspace's `cache.policy`: each task runs and refreshes the local cache. The remote is written only where `.vx/workspace.ts`'s own `cache.policy` names it, so a laptop's forced run never writes the cache CI reads; `vx run --force` is the flag. A `--cache-policy` or `VX_CACHE_POLICY` replaces the workspace's policy, this included.
+- `TURBO_SCM_BASE`, the base `turbo run --affected` compares with, is the run's base commit (`setBranch({ base })`): a bare `vx run build --affected` compares with the same ref. With it unset on GitHub Actions (`GITHUB_ACTIONS`), Turbo's own base applies: a pull request's `GITHUB_BASE_REF`, else the push event's `before` from `GITHUB_EVENT_PATH`. `TURBO_SCM_HEAD`, the commit Turbo compares up to, is vx's checkout: `--affected` compares the base with HEAD and its working tree, so a head at HEAD's commit (`$GITHUB_SHA` on a checkout of it) is honoured as is, and any other one is a warning to check that commit out.
 - Turbo hashes each package's `microfrontends.json` (or `.jsonc`) into every task, or the one file `VC_MICROFRONTENDS_CONFIG_FILE_NAME` names; so does `turbo()`.
+- `TURBO_ROOT_TURBO_JSON`, Turbo's root config path (against the cwd), is refused when it names another file than the workspace root's `turbo.json` or `turbo.jsonc`: `turbo()` reads only that one.
+- Turbo's run switches the plugins do not read, on purpose: `TURBO_CACHE`, `TURBO_REMOTE_CACHE_READ_ONLY` and `TURBO_REMOTE_ONLY` (core's `cache.policy` decides); `TURBO_CACHE_DIR`, `TURBO_CACHE_MAX_AGE` and `TURBO_CACHE_MAX_SIZE` (`cache.dir`; no run evicts); `TURBO_LOG_ORDER`, `TURBO_UI`, `TURBO_EXPERIMENTAL_UI`, `TURBO_TUI_SCROLLBACK_LENGTH` and `TURBO_LOG_VERBOSITY` (vx frames each task's output its own way); `TURBO_RUN_SUMMARY` and `TURBO_LOG_FILE` (`vx last`, telemetry plugins); `TURBO_EXPERIMENTAL_OTEL_*` (`@vzn/vx-otel`); `TURBO_DAEMON` (no daemon); `TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK` (no such check); `TURBO_ALLOW_NO_TURBO_JSON` (`turbo()` maps a turbo.json and refuses a root with none); `TURBO_PLATFORM_ENV` and `TURBO_PLATFORM_ENV_DISABLED` (Turbo warns of CI variables strict mode drops; a vx task never sees an undeclared variable, and no run warns); `TURBO_LOGIN`, `TURBO_SSO_LOGIN_CALLBACK_PORT` and `TURBO_CONFIG_DIR_PATH` (no login verb and no user config file: the token comes as [Tokens](#tokens-and-the-os-keychain) says); `TURBO_NO_UPDATE_NOTIFIER`, `TURBO_PRINT_VERSION_DISABLED`, `TURBO_GLOBAL_WARNING_DISABLED` and `TURBO_DOWNLOAD_LOCAL_ENABLED` (the `turbo` binary's own; vx runs none).
 - Turbo 2.11's `global` block (`futureFlags.globalConfiguration`) is read as the `globalDependencies`, `globalEnv` and `globalPassThroughEnv` it replaces, except that a task's `!` input takes a `global.inputs` file back, as Turbo prepends them to each task's inputs.
+- The root `package.json`'s `engines` (a non-empty object), which Turbo hashes into every task's key: each task's `inputs.workspaceRuntime` holds one `awk` line that prints that value alone, compacted, at the workspace root, named `rootEngines` in the written `vx-preset.ts`. `turbo()` and the written config carry the same line, so they key alike; raising `engines.node` re-runs every task, and no other root edit re-keys one. A reformat keys alike; reordering its keys misses (Turbo's map would hit). A config written while the root declared no `engines` keys none added later.
 - An unknown Turbo key is a todo naming it; `extends` is accepted and ignored (the overlay order above is what it means).
 
 ## `nx()` — an Nx repo, mid-migration
@@ -552,7 +557,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. An empty variable is unset, as Turbo reads it. A token with no URL 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 URL 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. An empty variable is unset, as Turbo reads it. With no URL the cache is Vercel's hosted Remote Cache (`https://vercel.com/api`), exactly as 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`; one that is not a JSON object is named in a warning and read as absent, where Turbo refuses it), then the root `turbo.json`'s `remoteCache` (`apiUrl`, `teamId`, `teamSlug`), whose `enabled: false` declines unless the options name a cache. As for `turbo`, these sources link a cache only with a team: a token without one is named in a warning, and with no team the plugin **declines** and the run stays local. A team with no token takes the token from the OS keychain ([Tokens](#tokens-and-the-os-keychain)). A `url`, `token` or `oidc` option names a cache with or without a team.
 
 | Option            | Environment variable                                                                                              | Meaning                                                                                                                                                                                                                                                                                               |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -632,7 +637,7 @@ With no token from an option, a variable or a config file, both plugins read the
 - Three outages in a row (no connection, no answer within the deadline, or a `5xx` once the resends are spent) open Turbo's outage breaker: no request is sent for 30 s, each lookup is a miss at once, then one request probes and its answer closes or reopens it. A hit is judged when its body ends, so a server that sends headers and then stalls the body counts the same way. A hung server costs three deadlines, not one per task.
 - A refused token (`401`/`403`) warns **once** and turns the layer off for the rest of the process (a `403` on an upload is a read-only token — Nx's spec, or turborepo-remote-cache's `READ_ONLY` and write-less JWTs: it turns off uploads alone, and reads go on) — including the requests already in flight when the refusal lands, which degrade in silence rather than repeating it (a six-project run printed five identical lines before 2026-09-20).
 - Policy (`--cache-policy=remote:r`, `VX_CACHE_POLICY`, `cache.policy`) is enforced by core, which layers each plugin's remote over the local cache — a read-only token pairs naturally with `remote:r`.
-- Core's policy alone decides reads and writes: the plugins read none of Turbo's or Nx's own switches (`TURBO_CACHE`, `TURBO_REMOTE_CACHE_READ_ONLY`, `NX_SKIP_REMOTE_CACHE`, `NX_DISABLE_REMOTE_CACHE`). A CI that keeps untrusted pull requests off the shared cache sets `cache.policy` or `--cache-policy=local:rw,remote:r` for them.
+- Core's policy alone decides reads and writes: the plugins read none of Turbo's or Nx's own switches (`TURBO_CACHE`, `TURBO_REMOTE_ONLY`, `TURBO_REMOTE_CACHE_READ_ONLY`, `NX_SKIP_REMOTE_CACHE`, `NX_DISABLE_REMOTE_CACHE`); `turbo()` reads `TURBO_FORCE`, as `--force`. A CI that keeps untrusted pull requests off the shared cache sets `cache.policy` or `--cache-policy=local:rw,remote:r` for them.
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.650",
+  "version": "0.0.651",
   "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.650"
+    "@vzn/vx": "^0.0.651"
   },
   "repository": {
     "type": "git",

package/src/adopt.ts

@@ -6,6 +6,9 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+// By namespace: bin.ts loads this before its release check, and a core
+// with no `ui` must still reach that refusal.
+import * as vx from '@vzn/vx'
 import { UserError } from '@vzn/vx'
 
 export type AdoptionMode = 'native' | 'keep'
@@ -270,8 +273,7 @@ async function runManager(
   const line = argv.join(' ')
   // The report's `install` row says what ran; a terminal sees it while it
   // runs, on a line the report then takes the place of.
-  const live = process.stdout.isTTY === true
-  if (live) process.stdout.write(`\n  ${line.slice(0, (process.stdout.columns ?? 80) - 4)} …`)
+  const clear = vx.ui.transient(line)
   // The manager's own output (progress, deprecations, audit, postinstalls)
   // is shown only when it fails: mid-init it buried the report (Growth's
   // first-run funnel F3, 2026-10-13).
@@ -300,9 +302,9 @@ async function runManager(
       failed = `: ${(e2 as Error).message}`
     }
   }
-  if (live) process.stdout.write('\r\x1b[2K\x1b[1A')
+  clear()
   if (code !== 0) {
-    process.stderr.write(said)
+    vx.ui.data('err', said)
     const missing = notServed(said)
     throw new UserError(
       missing === undefined

package/src/bin.ts

@@ -27,6 +27,9 @@ try {
   const { migrateCmd } = await import('./migrate.js')
   process.exitCode = await migrateCmd(process.argv.slice(2))
 } catch (err) {
+  // `ui` by namespace: a core older than it has none, and its refusal
+  // still reaches the reader.
+  const ui = (core as Partial<typeof core>).ui
   // Asked for JSON (`vx init --dry --format json` hands a Turbo or Nx repo
   // here), a refusal is core's error document on stdout too
   // (schemas/error.json): stdout was empty.
@@ -38,14 +41,11 @@ try {
     const docs = code.startsWith('VX_E_')
       ? { docs: `https://vznjs.github.io/vx/cli/#${code.toLowerCase()}` }
       : {}
-    process.stdout.write(
-      `${JSON.stringify({ ok: false, error: { code, message: `vx-migrate: ${message}`, ...docs } })}\n`,
-    )
+    const doc = `${JSON.stringify({ ok: false, error: { code, message: `vx-migrate: ${message}`, ...docs } })}\n`
+    if (ui === undefined) process.stdout.write(doc)
+    else ui.data('out', doc)
   }
   if (isUserError(err)) {
-    // `ui` by namespace: a core older than it has none, and its refusal
-    // still reaches the reader.
-    const ui = (core as Partial<typeof core>).ui
     if (ui === undefined) process.stderr.write(`vx-migrate: ${err.message}\n`)
     else ui.say('error', `vx-migrate: ${err.message}`)
     process.exitCode = 1

package/src/migrate-turbo.ts

@@ -14,6 +14,7 @@ import {
 import type { PackageMeta } from './packages.js'
 import { mapTurboWorkspace, type TurboGlobal, type TurboMappedProject } from './turbo/turbo-map.js'
 import { rootTaskProject } from './turbo/turbo-reads.js'
+import { ROOT_ENGINES_PROBE } from './turbo/root-engines.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'
@@ -86,6 +87,7 @@ export async function migrateTurbo(
     return {
       name: p.name,
       dir: p.dir,
+      ...(p.tags !== undefined ? { tags: p.tags } : {}),
       importLines: [
         ...(readsManifest ? [MANIFEST_IMPORT] : []),
         ...(sealed
@@ -246,10 +248,11 @@ function identifier(task: string): string {
 }
 
 /**
- * The `.env` probes, by name: Turbo hashes a task's `.env` files although
- * git ignores them, and a glob over git's files sees none, so the mapper
- * keys them through a shell line that prints each file. Inline in every
- * package's config, that line read as noise nobody could review.
+ * The probes, by name: Turbo hashes a task's `.env` files although git
+ * ignores them, and a glob over git's files sees none, so the mapper keys
+ * them through a shell line that prints each file; and the root's
+ * `engines`, which Turbo folds into every task. Inline in every package's
+ * config, each line read as noise nobody could review.
  */
 type Probe = { name: string; command: string }
 
@@ -262,6 +265,10 @@ const PROBES: readonly Probe[] = [
     name: 'dotenvFilesDeep',
     command: DOTENV_PROBE,
   },
+  {
+    name: 'rootEngines',
+    command: ROOT_ENGINES_PROBE,
+  },
 ]
 
 function nameProbes(projects: readonly TurboMappedProject[]): {

package/src/migrate.ts

@@ -429,7 +429,7 @@ async function lockWorkspace(root: string): Promise<{ code: number; said: string
   // A success's warnings print above the report; a refusal is said whole.
   // A success is a report row, matched as text: the colour FORCE_COLOR
   // gave the child would hide its `✓ vx lock` mark from that match.
-  if (code === 0) process.stderr.write(err)
+  if (code === 0) ui.data('err', err)
   return { code, said: code === 0 ? Bun.stripANSI(out) : out + err }
 }
 
@@ -613,7 +613,8 @@ async function keep(
     ...new Set(['@vzn/vx', '@vzn/vx-migrate', ...(declares ? all.map((p) => p.pkg) : [])]),
   ])
   if (args.json) {
-    process.stdout.write(
+    ui.data(
+      'out',
       `${JSON.stringify({
         dry: true,
         source,
@@ -637,7 +638,7 @@ async function keep(
   // A run reads only the lock; with the plugins installed it is written
   // now, else `next` names `vx lock` after the install.
   const lock = !args.dry && !next.includes(' lock && ') ? await lockWorkspace(root) : undefined
-  if (lock !== undefined && lock.code !== 0) process.stderr.write(lock.said)
+  if (lock !== undefined && lock.code !== 0) ui.data('err', lock.said)
   const rows: ui.FieldRow[] = [
     ['from', `${source}, run by ${runner}() from @vzn/vx-migrate`],
     ...(args.dry ? [['dry run', 'nothing written'] as const] : []),

package/src/nx/nx-map.ts

@@ -181,6 +181,7 @@ function checkNxNodes(nodes: Record<string, unknown>, label: string): void {
     const data = (n['data'] ?? {}) as Record<string, unknown>
     optional(data['root'], `${at}.data.root`, (v) => typeof v === 'string', 'a string')
     optional(data['targets'], `${at}.data.targets`, isRecord, 'an object of targets')
+    checkNamedInputs(data['namedInputs'], `${at}.data.namedInputs`, label)
     for (const [name, target] of Object.entries((data['targets'] ?? {}) as object)) {
       const t = `${at}.data.targets.${JSON.stringify(name)}`
       if (!isRecord(target)) refuse(t, 'an object')
@@ -195,6 +196,19 @@ function checkNxNodes(nodes: Record<string, unknown>, label: string): void {
   }
 }
 
+/**
+ * `namedInputs` as the mapper expands them: each name a list of inputs.
+ * A name holding an object or a number reached the expansion's loop and
+ * printed `TypeError: {} is not iterable` with its stack (fuzzed).
+ */
+function checkNamedInputs(v: unknown, at: string, label: string): void {
+  if (v === undefined) return
+  if (!isRecord(v)) throw new UserError(`${label}: ${at} must be an object of named inputs`)
+  for (const [name, members] of Object.entries(v))
+    if (!Array.isArray(members) || members.some((x) => typeof x !== 'string' && !isRecord(x)))
+      throw new UserError(`${label}: ${at}.${JSON.stringify(name)} must be an array of inputs`)
+}
+
 export interface MapNxOptions {
   /** nx.json's legacy `cacheableOperations`, for a graph whose targets carry no `cache` field. */
   readonly cacheable: ReadonlySet<string>
@@ -743,6 +757,7 @@ export async function readNxJsonFacts(root: string): Promise<NxJsonFacts> {
       sync?: { globalGenerators?: unknown }
     }
     const named = parsed?.namedInputs
+    checkNamedInputs(named ?? undefined, 'namedInputs', 'nx.json')
     const ops = parsed?.tasksRunnerOptions?.default?.options?.cacheableOperations
     return {
       namedInputs:
@@ -754,7 +769,8 @@ export async function readNxJsonFacts(root: string): Promise<NxJsonFacts> {
         ? parsed.sync.globalGenerators.filter((g): g is string => typeof g === 'string')
         : [],
     }
-  } catch {
+  } catch (err) {
+    if (err instanceof UserError) throw err
     // An unreadable nx.json (or base) just degrades named-input refs to TODOs.
     return none
   }

package/src/package-fs.ts

@@ -40,19 +40,35 @@ export function normalizeBunGlob(glob: string): string {
   return neg ? `!${g}` : g
 }
 
+/**
+ * Where the `[`…`]` class opening at `i` ends (a `]` right after the `[` is
+ * a member); `i` for a `[` with no `]`. A `,` `{` or `}` in a class is a
+ * member, never a brace cut, as `Bun.Glob` reads it.
+ */
+function classEnd(pattern: string, i: number): number {
+  const end = pattern.indexOf(']', i + 2)
+  return end === -1 ? i : end
+}
+
 /**
  * `pattern` with its first brace group expanded, recursively, while that
  * group holds a `/`: `Bun.Glob`'s scan finds nothing for one.
  */
 export function slashBraceExpansions(pattern: string): string[] {
   if (pattern.includes('\\')) return [pattern]
-  for (let open = pattern.indexOf('{'); open !== -1; open = pattern.indexOf('{', open + 1)) {
+  for (let open = 0; open < pattern.length; open++) {
+    if (pattern[open] === '[') {
+      open = classEnd(pattern, open)
+      continue
+    }
+    if (pattern[open] !== '{') continue
     let depth = 0
     const cuts: number[] = []
     let close = -1
     for (let i = open; i < pattern.length && close === -1; i++) {
       const c = pattern[i]
-      if (c === '{') depth++
+      if (c === '[') i = classEnd(pattern, i)
+      else if (c === '{') depth++
       else if (c === '}' && --depth === 0) close = i
       else if (c === ',' && depth === 1) cuts.push(i)
     }

package/src/remote-refusal.ts

@@ -27,5 +27,10 @@ export async function refusal(res: Response, what = ''): Promise<Error> {
   } catch {
     // quiet: the status alone still names the refusal
   }
-  return new Error(`${what}HTTP ${res.status}${said === '' ? '' : `: ${said.slice(0, 200)}`}`)
+  // Each control as `\xNN`: an `ESC ]` in the server's words retitled the terminal (L-31).
+  const line = said
+    .slice(0, 200)
+    // oxlint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
+  return new Error(`${what}HTTP ${res.status}${line === '' ? '' : `: ${line}`}`)
 }

package/src/turbo/index.ts

@@ -24,6 +24,7 @@ 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 {
+  ENV_CONDITION_KEYS,
   envNamesThatMap,
   microfrontendsConfigs,
   rootTaskProject,
@@ -71,12 +72,24 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
         const keys = await workspaceKeys(rootOf(ctx.workspaceRoot))
         if (workspace.run?.concurrency === undefined && keys.concurrency !== undefined)
           workspace.run = { ...workspace.run, concurrency: keys.concurrency }
+        // `TURBO_FORCE` (`true` or `1`, as Turbo reads it) is `turbo run --force`.
+        const force = Bun.env['TURBO_FORCE']?.trim()
+        if (force === 'true' || force === '1')
+          workspace.cache = { ...workspace.cache, policy: forcedPolicy(workspace.cache?.policy) }
         // `turbo run --affected` compares with TURBO_SCM_BASE when set, and
         // on GitHub Actions with what the event names.
         const base =
           Bun.env['TURBO_SCM_BASE']?.trim() ||
           githubActionsBase(rootOf(ctx.workspaceRoot), keys.remoteBaseFallback === true)
         if (base) ctx.setBranch({ base })
+        // ...up to TURBO_SCM_HEAD. vx's head is the checkout (HEAD and its
+        // working tree): a head at HEAD's commit is that, any other is said.
+        const head = Bun.env['TURBO_SCM_HEAD']?.trim()
+        if (head && !atHead(rootOf(ctx.workspaceRoot), head))
+          ctx.warn(
+            `TURBO_SCM_HEAD (${head}) is not the checked-out commit: --affected compares ` +
+              `the base with the checkout, so check out ${head} to compare with it.`,
+          )
       },
       // Turbo's packages are the package manager's members, each a project
       // with no vx.config written. `//#task` keys run on the root, as Turbo
@@ -99,6 +112,18 @@ export function turbo(options: TurboPluginOptions = {}): VxPlugin {
 
 const UNKNOWN_SHA = '0'.repeat(40)
 
+/** Whether `ref` names HEAD's commit. */
+function atHead(root: string, ref: string): boolean {
+  // An option is no ref; rev-parse prints `--end-of-options` back (git 2.43).
+  if (ref.startsWith('-')) return false
+  const proc = Bun.spawnSync(['git', 'rev-parse', 'HEAD', `${ref}^{commit}`], {
+    cwd: root,
+    stderr: 'ignore',
+  })
+  const [head, at] = proc.stdout.toString().split('\n')
+  return proc.exitCode === 0 && head === at
+}
+
 /**
  * Turbo's `--affected` base on GitHub Actions when `TURBO_SCM_BASE` is
  * unset (`get_github_base_ref`): a pull request's `GITHUB_BASE_REF`, else
@@ -185,6 +210,25 @@ async function workspaceKeys(root: string): Promise<{
   return out
 }
 
+/**
+ * A policy with every read off, as `--force` is: no hit is replayed. The
+ * remote is written only where the workspace's own policy names it, so a
+ * laptop's forced run never writes the cache CI reads.
+ */
+function forcedPolicy(spec = ''): string {
+  const flags = new Map([
+    ['local', 'w'],
+    ['remote', ''],
+  ])
+  for (const seg of spec.split(',')) {
+    if (seg.trim() === '') continue
+    const m = /^(local|remote):([rw]*)$/.exec(seg.trim())
+    if (m === null) return spec // core refuses it, naming `cache.policy`
+    flags.set(m[1]!, m[2]!.replace('r', ''))
+  }
+  return [...flags].map(([layer, f]) => `${layer}:${f}`).join(',')
+}
+
 const envNamesNow = (): string[] => Object.keys(process.env).sort()
 
 const textOf = (file: string): Promise<string> =>
@@ -223,6 +267,8 @@ async function run(root: string, projects: readonly ProjectMeta[]): Promise<Adop
       // An env wildcard expands over these; a new name it matches maps afresh.
       JSON.stringify(envNames),
       process.env['TURBO_CI_VENDOR_ENV_KEY'] ?? '',
+      // A framework conditional keys its names on these values (skew protection).
+      JSON.stringify(ENV_CONDITION_KEYS.map((k) => process.env[k] ?? null)),
       process.env['TURBO_ENV_MODE'] ?? '',
       ...configs,
       yarnrc,
@@ -265,6 +311,7 @@ async function mapAll(
     splice: (_kind, values) => values,
     persistentTodo: PERSISTENT_NOTE,
     envNames,
+    envValue: (name) => process.env[name],
     vendorEnvPrefix: process.env['TURBO_CI_VENDOR_ENV_KEY'] ?? '',
     envMode: process.env['TURBO_ENV_MODE'] ?? '',
     ...(tracked === null ? {} : { tracked: trackedKinds(tracked) }),

package/src/turbo/root-engines.ts

@@ -0,0 +1,19 @@
+/**
+ * The root manifest's `engines`, compacted, printed by one `awk` at the
+ * workspace root: Turbo folds that value into every task's global hash
+ * (crates/turborepo-task-hash/src/global_hash.rs), so raising
+ * `engines.node` re-ran every task under `turbo run` and replayed a hit
+ * under vx. A probe reads it live, so `turbo()` and the config the
+ * migration writes key it alike; it prints only the `engines` value, so
+ * no other root edit re-keys a task. A top-level JSON scanner, strings
+ * and escapes skipped, whitespace outside strings dropped: a reformat
+ * keys alike, a reorder misses (never a stale hit). One process, no Node.
+ */
+export const ROOT_ENGINES_PROBE =
+  'LC_ALL=C awk \'BEGIN{RS="\\001"}{n=length($0);d=0;q=0;c=0;o="";for(i=1;i<=n;i++){x=substr($0,i,1);if(c&&(q||x!~/[ \\t\\r\\n]/))o=o x;if(q){if(x=="\\\\"){i++;if(c)o=o substr($0,i,1)}else if(x=="\\""){q=0;if(d==1&&!c)k=substr($0,s,i-s)}continue}if(x=="\\""){q=1;s=i+1}else if(x=="{"||x=="[")d++;else if(x=="}"||x=="]"){d--;if(c&&d==1){print o;exit}}else if(x==":"&&d==1&&!c&&k=="engines")c=1}}\' package.json'
+
+/** Whether Turbo hashes the root's `engines`: a non-empty object, as it reads one. */
+export function keysRootEngines(rootPackageJson: unknown): boolean {
+  const engines = (rootPackageJson as { engines?: unknown } | null)?.engines
+  return typeof engines === 'object' && engines !== null && Object.keys(engines).length > 0
+}

package/src/turbo/turbo-map.ts

@@ -36,9 +36,12 @@ import {
   keyable,
   microfrontendsConfigs,
   ROOT,
+  TURBO_BUILTIN_PASS_THROUGH,
+  TURBO_DEFAULT_ENV,
   turboConfigFile,
 } from './turbo-reads.js'
 import type { TrackedKinds } from '../tracked-outputs.js'
+import { keysRootEngines, ROOT_ENGINES_PROBE } from './root-engines.js'
 import {
   DOTENV_PROBE,
   DOTENV_PROBE_TOP,
@@ -72,6 +75,8 @@ interface TurboJson {
   /** Turbo 2.11 `futureFlags.globalConfiguration`: the global lists live here. */
   global?: { inputs?: string[]; env?: string[]; passThroughEnv?: string[]; envMode?: unknown }
   envMode?: unknown
+  /** Turbo 2.11.6: the package's labels, which `--filter tag:` selects by. */
+  tags?: string[]
 }
 
 const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
@@ -133,6 +138,18 @@ function explicitEnv(
   return out.filter((n) => !excluded.some((re) => re.test(n)))
 }
 
+/**
+ * The literal names of Turbo's builtin pass-through list, the same under
+ * `turbo()` as in written configs: `exec.env.passThrough` is keyed by name,
+ * so a list matched against the live environment keyed each machine apart
+ * and missed the cache `turbo()` filled once the configs were written. A
+ * wildcard family is a note. A name that is no shell variable name
+ * (`ProgramFiles(x86)`) is left out: core refuses it there.
+ */
+const BUILTIN_PASS_THROUGH = TURBO_BUILTIN_PASS_THROUGH.filter((e) =>
+  /^[A-Za-z_][A-Za-z0-9_]*$/.test(e),
+)
+
 /** A gap's message: a wildcard, or a literal name core cannot key. */
 const envGap = (field: string, entry: string, literal: string | null, list: string): string =>
   literal === null
@@ -161,8 +178,11 @@ const KNOWN_TASK_KEYS = new Set([
   // watch` keeps it up and restarts it only when its config changes or it
   // dies, so either value maps to nothing.
   'interruptible',
-  // Labels: Turbo keeps them out of the hash and the behaviour.
+  // Turbo 2.11.6 selects a task by them (`--filter tag:`); a vx tag belongs
+  // to a project, so only the package-level `tags` map (`packageTags`).
   'tags',
+  // Turbo parses it for external CI tooling and acts on nothing.
+  'experimentalCI',
 ])
 
 // Turbo's per-task `outputLogs` against vx's per-run `--output-logs`.
@@ -191,6 +211,8 @@ export interface TurboMappedTask {
 export interface TurboMappedProject {
   name: string
   dir: string
+  /** The package's turbo.json `tags`, its vx project tags. */
+  tags?: string[]
   tasks: TurboMappedTask[]
 }
 
@@ -222,6 +244,12 @@ export interface MapTurboOptions {
    * Absent (`bunx @vzn/vx-migrate` writes files), a wildcard is a todo.
    */
   envNames?: readonly string[]
+  /**
+   * A variable's value where the tasks will run, read only for a framework
+   * conditional's key (Turbo's `envConditionals`). Absent (written configs),
+   * every conditional name is keyed: more misses, never a stale hit.
+   */
+  envValue?: (name: string) => string | undefined
   /**
    * Without `envNames` (written configs): the upper-case names the files
    * under `dirs` spell, which a framework's `*` prefix is matched against.
@@ -354,10 +382,12 @@ const TOP_LISTS = [
   'globalPassThroughEnv',
   'globalDotEnv',
   'extends',
+  'tags',
 ]
 const GLOBAL_LISTS = ['inputs', 'env', 'passThroughEnv']
 const TASK_LISTS = ['dependsOn', 'outputs', 'env', 'passThroughEnv', 'with', 'dotEnv']
 const TASK_FLAGS = ['cache', 'persistent', 'interactive', 'interruptible']
+const ENV_LISTS = new Set(['globalEnv', 'globalPassThroughEnv', 'env', 'passThroughEnv'])
 
 /**
  * The shape of every field the mapper reads, refused by name. A number
@@ -373,12 +403,47 @@ function checkTurboShape(cfg: unknown, label: string): void {
     if (v !== undefined && (!Array.isArray(v) || v.some((x) => typeof x !== 'string')))
       refuse(at, 'an array of strings')
   }
+  // Turbo refuses `$NAME` in an env list (`InvalidEnvPrefix`), its own
+  // `$TURBO_EXTENDS$` aside; mapped, core keyed a variable literally
+  // named `$NAME`, which is never set.
+  const envList = (v: unknown, at: string): void => {
+    list(v, at)
+    const bad = (v as string[] | undefined)?.find(
+      (x) => x.startsWith('$') && x !== '$TURBO_EXTENDS$',
+    )
+    if (bad !== undefined)
+      throw new UserError(
+        `${label}: ${at} holds ${JSON.stringify(bad)}: Turbo refuses a "$" before an env name — write ${JSON.stringify(bad.slice(1))}`,
+      )
+  }
+  // Turbo refuses an absolute glob (`AbsolutePathInConfig`), read past its
+  // `!` and `$TURBO_ROOT$/`; mapped, core refused it naming the project,
+  // as if its own config held it.
+  const paths = (v: unknown, at: string): void => {
+    for (const x of Array.isArray(v) ? v : []) {
+      const globs: unknown[] = isRecord(x) && Array.isArray(x['globs']) ? x['globs'] : [x]
+      for (const g of globs) {
+        if (typeof g !== 'string') continue
+        const bare = g.replace(/^!/, '').replace(/^\$TURBO_ROOT\$\//, '')
+        if (path.isAbsolute(bare))
+          throw new UserError(
+            `${label}: ${at} holds ${JSON.stringify(g)}: Turbo refuses an absolute path — name it relative to the package, or to the root with $TURBO_ROOT$/`,
+          )
+      }
+    }
+  }
   if (!isRecord(cfg)) refuse('the file', 'a JSON object')
   const c = cfg as Record<string, unknown>
-  for (const k of TOP_LISTS) list(c[k], k)
+  for (const k of TOP_LISTS) (ENV_LISTS.has(k) ? envList : list)(c[k], k)
+  paths(c['globalDependencies'], 'globalDependencies')
   if (c['global'] !== undefined) {
     if (!isRecord(c['global'])) refuse('global', 'an object')
-    for (const k of GLOBAL_LISTS) list((c['global'] as Record<string, unknown>)[k], `global.${k}`)
+    for (const k of GLOBAL_LISTS)
+      (ENV_LISTS.has(k) ? envList : list)(
+        (c['global'] as Record<string, unknown>)[k],
+        `global.${k}`,
+      )
+    paths((c['global'] as Record<string, unknown>)['inputs'], 'global.inputs')
   }
   for (const field of ['tasks', 'pipeline']) {
     const tasks = c[field]
@@ -388,7 +453,7 @@ function checkTurboShape(cfg: unknown, label: string): void {
       const at = `${field}.${JSON.stringify(name)}`
       if (!isRecord(def)) refuse(at, 'an object')
       const d = def as Record<string, unknown>
-      for (const k of TASK_LISTS) list(d[k], `${at}.${k}`)
+      for (const k of TASK_LISTS) (ENV_LISTS.has(k) ? envList : list)(d[k], `${at}.${k}`)
       // Turbo 2.11 adds `{ mode, globs, withDefaults }` entries (`flatInputs`).
       const inputs = d['inputs']
       if (
@@ -396,6 +461,8 @@ function checkTurboShape(cfg: unknown, label: string): void {
         (!Array.isArray(inputs) || inputs.some((x) => typeof x !== 'string' && !isRecord(x)))
       )
         refuse(`${at}.inputs`, 'an array of globs')
+      paths(inputs, `${at}.inputs`)
+      paths(d['outputs'], `${at}.outputs`)
       for (const k of TASK_FLAGS)
         if (d[k] !== undefined && typeof d[k] !== 'boolean') refuse(`${at}.${k}`, 'true or false')
       for (const k of ['outputLogs', 'outputMode'])
@@ -404,6 +471,16 @@ function checkTurboShape(cfg: unknown, label: string): void {
   }
 }
 
+/**
+ * A package's top-level turbo.json `tags`, which Turbo 2.11.6's `--filter
+ * tag:<label>` selects every task of the package by, as vx's `tag:` does a
+ * project's. Its own file only: Turbo inherits no package tag, and the
+ * root's label the root package. Blank ones dropped, as vx refuses them.
+ */
+function packageTags(cfg: TurboJson | undefined): string[] {
+  return [...new Set((cfg?.tags ?? []).filter((t) => t.trim() !== ''))]
+}
+
 function tasksOf(cfg: TurboJson): Record<string, TurboTask> {
   return cfg.tasks ?? cfg.pipeline ?? {}
 }
@@ -762,6 +839,22 @@ async function rootPackageJson(root: string): Promise<PackageMeta['packageJson']
   return (pkg !== null && typeof pkg === 'object' ? pkg : {}) as PackageMeta['packageJson']
 }
 
+/**
+ * `turboConfigFile`, refusing a directory that holds both files as Turbo
+ * does (vercel/turborepo#10083): `turbo.json` shadowed the `.jsonc` beside
+ * it in silence, so an edit there keyed and ran nothing.
+ */
+async function onlyConfigFile(dir: string, root: string): Promise<string | null> {
+  const file = await turboConfigFile(dir)
+  if (file?.endsWith('.json') === true && (await Bun.file(`${file}c`).exists())) {
+    const where = dir === root ? 'the workspace root' : relPosix(root, dir)
+    throw new UserError(
+      `${where} holds both turbo.json and turbo.jsonc: Turbo refuses this — remove one`,
+    )
+  }
+  return file
+}
+
 export async function mapTurboWorkspace(
   root: string,
   metas: readonly PackageMeta[],
@@ -769,7 +862,16 @@ export async function mapTurboWorkspace(
 ): Promise<TurboMapping> {
   // A workspace with no Turbo config answered with a bare ENOENT and a stack
   // (item 1043): turbo() declared in the wrong repo, or its file removed.
-  const rootFile = await turboConfigFile(root)
+  const rootFile = await onlyConfigFile(root, root)
+  // Turbo reads its root config from the file TURBO_ROOT_TURBO_JSON names,
+  // against the cwd (vercel/turborepo#9087); reading the root's in its
+  // place ran another task graph than `turbo run`.
+  const named = Bun.env['TURBO_ROOT_TURBO_JSON']
+  if (named && (rootFile === null || path.resolve(named) !== rootFile)) {
+    throw new UserError(
+      `TURBO_ROOT_TURBO_JSON names ${path.resolve(named)}: turbo() reads only the workspace root's turbo.json or turbo.jsonc — unset it, or move that config to the root`,
+    )
+  }
   if (rootFile === null) {
     throw new UserError(
       `no turbo.json or turbo.jsonc at the workspace root (${root}): turbo() maps a Turbo repo's config — add one, or remove turbo() from .vx/workspace.ts`,
@@ -829,6 +931,7 @@ export async function mapTurboWorkspace(
   // over git's files keyed nothing: the workspace probe keys them (item
   // 1032).
   const rootMeta = metas.find((m) => path.resolve(m.dir) === path.resolve(root))
+  const rootPkg = rootMeta?.packageJson ?? (await rootPackageJson(root))
   const globalFiles = [
     ...globalDeps.filter((d) => envDependency(d) === null).map(turboGlobstar),
     ...(rootCfg.globalDotEnv ?? []),
@@ -837,7 +940,7 @@ export async function mapTurboWorkspace(
     // packages that depend on the database package).
     ...(rootCfg.tasks === undefined && rootCfg.pipeline !== undefined
       ? []
-      : rootDependencyGlobs(root, rootMeta?.packageJson ?? (await rootPackageJson(root)), metas)),
+      : rootDependencyGlobs(root, rootPkg, metas)),
     ...microfrontendsConfigs(root, [root, ...metas.map((m) => m.dir)]).map((c) => c.rel),
   ]
   const rootDotenv = globalFiles.filter((f) => isDotenvGlob(f))
@@ -851,18 +954,31 @@ export async function mapTurboWorkspace(
   const globals = {
     inputs: globalFiles.filter((f) => !isDotenvGlob(f) && !globalIgnored.includes(f)),
     env: [
-      ...envNames('globalEnv', rootCfg.globalEnv ?? []),
+      // Turbo's defaults sit before the user's list, so its `!` takes them back.
+      ...envNames('globalEnv', [...TURBO_DEFAULT_ENV, ...(rootCfg.globalEnv ?? [])]),
       ...globalDeps.flatMap((d) => envDependency(d) ?? []),
     ],
-    pass: envNames('globalPassThroughEnv', rootCfg.globalPassThroughEnv ?? []),
+    pass: [
+      ...envNames('globalPassThroughEnv', rootCfg.globalPassThroughEnv ?? []),
+      ...BUILTIN_PASS_THROUGH,
+    ],
   }
 
+  // A written config names no variable by pattern: Turbo's builtin
+  // families are the user's to list, once, for the tasks that read them.
+  if (opts.envNames === undefined && opts.sourceNames !== undefined)
+    notes.push(
+      `Turbo passes every ${TURBO_BUILTIN_PASS_THROUGH.filter((e) => e.endsWith('*')).join(', ')} ` +
+        'variable to each task; the configs pass its literal names only — add the ones a task ' +
+        'reads to exec.env.passThrough',
+    )
+
   // The workspace root as a project (a `vx.config` there, D-39) holds
   // Turbo's `//#task`s (`rootMeta`, above); Turbo runs no plain task in the root package.
   const files = new Map<string, TurboJson>([[ROOT, rootCfg]])
   for (const meta of metas) {
     if (meta === rootMeta) continue
-    const file = await turboConfigFile(meta.dir)
+    const file = await onlyConfigFile(meta.dir, root)
     if (file !== null) files.set(meta.name, await readTurboJson(file, root))
   }
 
@@ -1113,6 +1229,8 @@ export async function mapTurboWorkspace(
         const head = e.slice(0, -1)
         return live.filter((n) => n.startsWith(head)).sort()
       })
+      for (const c of fw.conditionals ?? [])
+        if (opts.envValue?.(c.key) === c.value) names.push(...c.include)
       inferredOf.set(m.name, vendor ? names.filter((n) => !n.startsWith(vendor)) : names)
     } else if (opts.sourceNames !== undefined) {
       // A written config cannot ask the run's environment, and with the
@@ -1125,11 +1243,15 @@ export async function mapTurboWorkspace(
         m.name,
         // The bare prefix is no name: formbricks' web spells `NEXT_PUBLIC_`
         // in a `startsWith` test, and the configs keyed a variable of it.
-        fw.env.flatMap((e) => {
-          if (!e.endsWith('*')) return [e]
-          const head = e.slice(0, -1)
-          return spelled.filter((n) => n.startsWith(head) && n.length > head.length)
-        }),
+        [
+          ...fw.env.flatMap((e) => {
+            if (!e.endsWith('*')) return [e]
+            const head = e.slice(0, -1)
+            return spelled.filter((n) => n.startsWith(head) && n.length > head.length)
+          }),
+          // Written for another environment: keyed whatever the condition.
+          ...(fw.conditionals ?? []).flatMap((c) => c.include),
+        ],
       )
       sourcedOf.set(fw, [...(sourcedOf.get(fw) ?? []), m.name])
     } else usersOf.set(fw, [...(usersOf.get(fw) ?? []), m.name])
@@ -1323,7 +1445,8 @@ export async function mapTurboWorkspace(
       tasks.push(mapped)
     }
     excludeSiblingOutputs(resolveSharedOutputs(tasks))
-    projects.push({ name: meta.name, dir: meta.dir, tasks })
+    const tags = packageTags(meta === rootMeta ? rootCfg : files.get(meta.name))
+    projects.push({ name: meta.name, dir: meta.dir, ...(tags.length > 0 ? { tags } : {}), tasks })
   }
 
   // Turbo 2.11's `dependencyOutputs` input hashes the named files after
@@ -1426,6 +1549,14 @@ export async function mapTurboWorkspace(
     }
   }
 
+  if (keysRootEngines(rootPkg))
+    for (const p of projects)
+      for (const t of p.tasks) {
+        const inputs = t.task?.['inputs'] as Record<string, unknown> | undefined
+        if (inputs === undefined) continue
+        const probes = (inputs['workspaceRuntime'] as unknown[] | undefined) ?? []
+        inputs['workspaceRuntime'] = [...probes, ROOT_ENGINES_PROBE]
+      }
   nestedInputs(root, projects)
   for (const [entry, n] of wildcardUses)
     notes.push(
@@ -1446,9 +1577,42 @@ export async function mapTurboWorkspace(
   pruneUnreachedPersistentNotes(projects, metas, opts.persistentTodo)
   pruneOrphanPersistentNotes(projects, opts.persistentTodo)
   refuseTaskNames(projects, 'task')
+  sortOrderFree(projects)
   return { projects, notes, globals }
 }
 
+function byText(a: unknown, b: unknown): number {
+  const x = typeof a === 'string' ? a : JSON.stringify(a)
+  const y = typeof b === 'string' ? b : JSON.stringify(b)
+  return x < y ? -1 : x > y ? 1 : 0
+}
+
+function negationsLast(a: unknown, b: unknown): number {
+  const neg = (g: unknown) => Number(typeof g === 'string' && g.startsWith('!'))
+  return neg(a) - neg(b) || byText(a, b)
+}
+
+/**
+ * Turbo sorts a task's `outputs` and `dependsOn` before hashing, so
+ * reordering them in turbo.json keeps the hit (vercel/turborepo#2064).
+ * Core keys a config's lists as written, and gives neither list's order a
+ * meaning: an edge set, and a `!` output takes back from the positives
+ * wherever it stands (`outputMatcher`). Sorted here, negations last, so
+ * the reorder keys the same and a written config reads the same.
+ */
+function sortOrderFree(projects: readonly TurboMappedProject[]): void {
+  for (const p of projects)
+    for (const t of p.tasks) {
+      const task = t.task
+      if (task === null) continue
+      if (Array.isArray(task['dependsOn'])) task['dependsOn'] = [...task['dependsOn']].sort(byText)
+      const outputs = (task['cache'] as { outputs?: Record<string, unknown> } | undefined)?.outputs
+      if (outputs === undefined) continue
+      for (const k of ['files', 'workspaceFiles'])
+        if (Array.isArray(outputs[k])) outputs[k] = [...outputs[k]].sort(negationsLast)
+    }
+}
+
 /**
  * Turbo hashes a package's files as git lists them, nested workspace
  * packages included (probed on 2.11.6: `a#build` keys `n/x.ts` of a
@@ -1800,6 +1964,12 @@ function buildTask(
           todos.push(
             `dependsOn ${JSON.stringify(d)}: no workspace package is named ${pkg} — edge dropped`,
           )
+        // Turbo runs a root task only when turbo.json names it `//#x`; the
+        // script alone is not enough (vercel/turborepo#3592).
+        else if (d.startsWith(`${ROOT}#`))
+          todos.push(
+            `dependsOn ${JSON.stringify(d)}: turbo.json defines no "${d}" task — edge dropped`,
+          )
         else
           todos.push(
             `dependsOn ${JSON.stringify(d)}: ${pkg} declares no ${task} script — edge dropped`,
@@ -1961,6 +2131,14 @@ function buildTask(
     if (files.length > 0 && files.every((f) => typeof f === 'string' && f.startsWith('!'))) {
       files.unshift('**/*')
     }
+    // Turbo keys the package's own package.json beside any explicit
+    // `inputs` (PACKAGE_CONFIG_INPUTS, turborepo#1832): without it, an edit
+    // to its `exports` or `type` replayed the old build. A glob naming it
+    // already, or an exclusion of it, is left as written.
+    const named = files.some(
+      (g) => typeof g === 'string' && new Bun.Glob(g.replace(/^!/, '')).match('package.json'),
+    )
+    if (!named) files.push('package.json')
   }
   // Turbo 1's task `dotEnv`: package-relative `.env` files it hashes,
   // gitignored as a rule, so read as files they keyed nothing (item 1032).
@@ -2072,8 +2250,10 @@ function buildTask(
   const rewritesManifest = takeBacks.includes('!package.json')
 
   if (atRoot) wsOutFiles.unshift(...outFiles.splice(0))
-  const outputs: Record<string, unknown> = { files: takingBack(outFiles) }
-  const ws = takingBack(wsOutFiles)
+  // Sorted here, before the passes that take them back from other tasks'
+  // inputs, so those `!` entries come in this order too (`sortOrderFree`).
+  const outputs: Record<string, unknown> = { files: takingBack(outFiles).sort(negationsLast) }
+  const ws = takingBack(wsOutFiles).sort(negationsLast)
   if (ws.length > 0) outputs.workspaceFiles = ws
   task.cache = {
     outputs,

package/src/turbo/turbo-reads.ts

@@ -37,6 +37,8 @@ export const FRAMEWORK_ENV: ReadonlyArray<{
   env: readonly string[]
   all: boolean
   dependencies: readonly string[]
+  /** Turbo's `envConditionals`: `include` is keyed while `key` holds `value`. */
+  conditionals?: ReadonlyArray<{ key: string; value: string; include: readonly string[] }>
 }> = [
   { slug: 'astro', env: ['PUBLIC_*'], all: true, dependencies: ['astro'] },
   { slug: 'blitzjs', env: ['NEXT_PUBLIC_*'], all: true, dependencies: ['blitz'] },
@@ -53,6 +55,10 @@ export const FRAMEWORK_ENV: ReadonlyArray<{
     env: ['NEXT_PUBLIC_*', 'NEXT_DEPLOYMENT_ID'],
     all: true,
     dependencies: ['next'],
+    // Skew protection builds the deployment id into the app (vercel/turborepo#9853).
+    conditionals: [
+      { key: 'VERCEL_SKEW_PROTECTION_ENABLED', value: '1', include: ['VERCEL_DEPLOYMENT_ID'] },
+    ],
   },
   {
     slug: 'nitro',
@@ -85,20 +91,105 @@ export const FRAMEWORK_ENV: ReadonlyArray<{
   },
 ]
 
+/** The variables each framework conditional reads; a live mapping is keyed on their values. */
+export const ENV_CONDITION_KEYS: readonly string[] = FRAMEWORK_ENV.flatMap((f) =>
+  (f.conditionals ?? []).map((c) => c.key),
+)
+
+// Turbo's own env, from crates/turborepo-env (2026-10-27, edace4621): the
+// promise is a Turbo repo run unchanged, so these mirror it exactly.
+/** `DEFAULT_ENV_VARS`: hashed into every task as if listed in `globalEnv` (a `!` there takes them back). */
+export const TURBO_DEFAULT_ENV: readonly string[] = ['VERCEL_ANALYTICS_ID', 'VERCEL_TARGET_ENV']
+/** `BUILTIN_PASS_THROUGH_ENV`: passed to every task, never hashed. */
+export const TURBO_BUILTIN_PASS_THROUGH: readonly string[] = [
+  'HOME',
+  'USER',
+  'TZ',
+  'LANG',
+  'SHELL',
+  'PWD',
+  'XDG_DATA_*',
+  'XDG_RUNTIME_DIR',
+  'XAUTHORITY',
+  'DBUS_SESSION_BUS_ADDRESS',
+  'CI',
+  'NODE_OPTIONS',
+  'COREPACK_*',
+  'LD_LIBRARY_PATH',
+  'DYLD_FALLBACK_LIBRARY_PATH',
+  'LIBPATH',
+  'LD_PRELOAD',
+  'DYLD_INSERT_LIBRARIES',
+  'COLORTERM',
+  'FORCE_COLOR',
+  'NO_COLOR',
+  'TERM',
+  'TERM_PROGRAM',
+  'DISPLAY',
+  'TMP',
+  'TEMP',
+  'WINDIR',
+  'ProgramFiles',
+  'ProgramFiles(x86)',
+  'VSCODE_*',
+  'ELECTRON_RUN_AS_NODE',
+  'DOCKER_*',
+  'BUILDKIT_*',
+  'COMPOSE_*',
+  'JB_IDE_*',
+  'JB_INTERPRETER',
+  '_JETBRAINS_TEST_RUNNER_RUN_SCOPE_TYPE',
+  'TURBO_*',
+  'VERCEL',
+  'VERCEL_*',
+  'NEXT_*',
+  'USE_OUTPUT_FOR_EDGE_FUNCTIONS',
+  'NOW_BUILDER',
+  'VC_MICROFRONTENDS_CONFIG_FILE_NAME',
+  'GITHUB_*',
+  'RUNNER_*',
+  '__NIXOS_*',
+  'NIX_*',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'PATH',
+  'PROGRAMDATA',
+  'SYSTEMROOT',
+  'SYSTEMDRIVE',
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'PNPM_HOME',
+  'pnpm_config_verify_deps_before_run',
+  'NPM_CONFIG_STORE_DIR',
+  'COMSPEC',
+  'PATHEXT',
+]
+
 /** 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
+ * one of `configs` (turbo.json texts, any string, a superset), in Turbo's
+ * framework table or in its builtin env matches, each of those tables'
+ * literals, 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('*')))
+  const patterns = new Set(
+    [...FRAMEWORK_ENV.flatMap((f) => f.env), ...TURBO_BUILTIN_PASS_THROUGH].filter((e) =>
+      e.includes('*'),
+    ),
+  )
+  // A builtin or conditional literal is passed or keyed only when set.
+  const literals = new Set([
+    ...TURBO_BUILTIN_PASS_THROUGH.filter((e) => !e.includes('*')),
+    ...FRAMEWORK_ENV.flatMap((f) => (f.conditionals ?? []).flatMap((c) => c.include)),
+  ])
   for (const text of configs)
     for (const m of text.matchAll(/"((?:[^"\\]|\\.)*)"/g))
       if (m[1]!.includes('*')) patterns.add(m[1]!)
@@ -110,7 +201,7 @@ export function envNamesThatMap(configs: readonly string[], names: readonly stri
         `^${p.replaceAll('\\', '').replace(/^!/, '').split('*').map(RegExp.escape).join('.*')}$`,
       ),
   )
-  return names.filter((n) => !keyable(n) || res.some((re) => re.test(n)))
+  return names.filter((n) => !keyable(n) || literals.has(n) || res.some((re) => re.test(n)))
 }
 
 /**

package/src/turbo-cache/index.ts

@@ -23,6 +23,7 @@ import {
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
+  ui,
   UserError,
   type PluginOptionKinds,
 } from '@vzn/vx'
@@ -265,7 +266,7 @@ export function resolveTurboCacheConfig(
   file: TurboJsonRemoteCache = {},
   /** The repo's `.turbo/config.json` (`turbo link` writes it): below the environment, above turbo.json. */
   local: TurboLocalConfig = {},
-  warn: (message: string) => void = (m) => console.error(`[vx] plugin '@vzn/vx-migrate': ${m}`),
+  warn: (message: string) => void = (m) => ui.say('warn', `[vx] plugin '@vzn/vx-migrate': ${m}`),
 ): TurboCacheConfig | undefined {
   // `enabled: false` turns Turbo's remote cache off whatever the env says;
   // options name a cache for vx alone, and win.
@@ -301,10 +302,20 @@ export function resolveTurboCacheConfig(
     fromFile(file.teamId)
   const teamSlug =
     options.teamSlug ?? set('TURBO_TEAM') ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
-  // Turbo's own default when a token or a team is set and no URL is:
-  // Vercel's hosted Remote Cache. A token alone is a configured cache, as it
-  // is for `turbo`; a URL or a team without one asks the OS keychain at
-  // `open`; none of them is the declined, local run.
+  // Turbo uses its remote only when linked, a team set (`is_linked`): a
+  // token without one ran remote here, team-less, where `turbo` runs local.
+  // An option naming the cache is vx's own, and stands.
+  const named =
+    options.url !== undefined || options.token !== undefined || options.oidc !== undefined
+  if (!named && teamId === undefined && teamSlug === undefined) {
+    if (token !== undefined)
+      warn(
+        'a Turbo token is set but no team (TURBO_TEAM, TURBO_TEAMID or .turbo/config.json): remote cache off for this run, as for turbo',
+      )
+    return undefined
+  }
+  // Turbo's own default when no URL is set: Vercel's hosted Remote Cache.
+  // A team without a token asks the OS keychain at `open`.
   // Each source with its name: TURBO_API was refused as a `url`
   // option the workspace never set.
   const [rawUrl, urlFrom] =
@@ -899,16 +910,31 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 /**
  * The repo's `.turbo/config.json`, by Turbo's field names and their
  * aliases (`apiurl`, `ApiUrl`, `APIURL`, …); `{}` when absent or unreadable.
+ * One that does not parse is named: Turbo refuses it, and read as absent
+ * in silence a linked repo lost its remote with no word.
  */
-function localConfigOf(root: string): TurboLocalConfig {
-  let raw: unknown
+function localConfigOf(root: string, warn: (message: string) => void): TurboLocalConfig {
+  let text: string
   try {
-    raw = JSON.parse(readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8'))
+    text = readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8')
     // quiet: a local config file: none read is none linked
   } catch {
     return {}
   }
-  if (typeof raw !== 'object' || raw === null) return {}
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch (err) {
+    warn(
+      `.turbo/config.json does not parse as a JSON object (${(err as Error).message}): read as absent`,
+    )
+    return {}
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    const kind = Array.isArray(raw) ? 'an array' : raw === null ? 'null' : `a ${typeof raw}`
+    warn(`.turbo/config.json does not parse as a JSON object (${kind}): read as absent`)
+    return {}
+  }
   const byLower = new Map(Object.entries(raw).map(([k, v]) => [k.toLowerCase(), v]))
   return {
     apiUrl: byLower.get('apiurl'),
@@ -1004,12 +1030,13 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
   let opened: { layer: TurboRemoteCache; warn: (m: string) => void } | undefined
   return definePlugin(import.meta, {
     cache(ctx): RemoteCacheLayer | undefined {
+      const warn = (m: string) => ctx.warn(`[vx] plugin '@vzn/vx-migrate': ${m}`)
       const config = resolveTurboCacheConfig(
         options,
         Bun.env,
         remoteCacheOf(ctx.workspaceRoot),
-        localConfigOf(ctx.workspaceRoot),
-        (m) => ctx.warn(`[vx] plugin '@vzn/vx-migrate': ${m}`),
+        localConfigOf(ctx.workspaceRoot, warn),
+        warn,
       )
       if (config === undefined) return undefined
       // A signed download waits in a temp until its tag checks: in vx's