fix(env): isolate direct shims from package manager selection

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/shim_package_manager_version_overrides/check.cjs

@@ -0,0 +1,15 @@
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const { delimiter } = require('node:path');
+
+// Start each child at the shim even though the parent Node process has injected tool paths.
+const env = {
+  ...process.env,
+  PATH: [process.env.VP_HOME + '/bin', '/usr/bin', '/bin'].join(delimiter),
+  VP_PATH_INJECTED_TOOLS: '',
+};
+const [tool, expected] = process.argv.slice(2);
+const args = tool === 'vp' ? ['install', '--', '--version'] : ['--version'];
+const actual = execFileSync(tool, args, { env, encoding: 'utf8' }).trim();
+assert.equal(actual, expected);
+console.log(`${tool} uses the expected version`);

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/shim_package_manager_version_overrides/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "shim-package-manager-version-overrides",
+  "private": true,
+  "packageManager": "pnpm@10.18.0"
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/shim_package_manager_version_overrides/snapshots.toml

@@ -0,0 +1,11 @@
+[[case]]
+name = "selection_override_does_not_change_shims"
+vp = "global"
+skip-platforms = ["windows"]
+env = { VP_PACKAGE_MANAGER = "pnpm@10.19.0", npm_config_manage_package_manager_versions = "false" }
+steps = [
+  { argv = ["node", "check.cjs", "pnpm", "10.18.0"], comment = "The matching shim still uses the project pin" },
+  { argv = ["node", "check.cjs", "vp", "10.19.0"], comment = "vp install still uses VP_PACKAGE_MANAGER" },
+  { argv = ["node", "check.cjs", "pnpm", "10.18.0"], envs = [["VP_PACKAGE_MANAGER", "invalid"]], comment = "An invalid selection does not affect direct shims" },
+]
+

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/shim_package_manager_version_overrides/snapshots/selection_override_does_not_change_shims.md

@@ -0,0 +1,25 @@
+# selection_override_does_not_change_shims
+
+## `node check.cjs pnpm 10.18.0`
+
+The matching shim still uses the project pin
+
+```
+pnpm uses the expected version
+```
+
+## `node check.cjs vp 10.19.0`
+
+vp install still uses VP_PACKAGE_MANAGER
+
+```
+vp uses the expected version
+```
+
+## `VP_PACKAGE_MANAGER=invalid node check.cjs pnpm 10.18.0`
+
+An invalid selection does not affect direct shims
+
+```
+pnpm uses the expected version
+```

crates/vp_global_cli/src/commands/env/package_manager.rs

@@ -13,6 +13,24 @@ pub(crate) async fn resolve_current(
     resolve_current_for(cwd, None).await
 }
 
+/// Selecting a manager for vp commands must not change direct shim versions.
+pub(crate) async fn resolve_shim_for(
+    cwd: &AbsolutePath,
+    expected: PackageManagerType,
+) -> Result<Option<EnvironmentPackageManagerResolution>, Error> {
+    let session = config::read_session_package_manager().await;
+    let session = session.as_deref().map(parse_package_manager_spec_with_hash).transpose()?;
+    let default = configured_default_for(&config::load_config().await?, expected)?;
+    resolve_environment_package_manager(
+        cwd,
+        session.as_ref().map(|(kind, version, hash)| (*kind, version.as_str(), hash.as_deref())),
+        default.as_ref().map(|(kind, version, hash)| (*kind, version.as_str(), hash.as_deref())),
+        Some(expected),
+    )
+    .await
+    .map_err(Error::from)
+}
+
 pub(crate) async fn resolve_current_for(
     cwd: &AbsolutePath,
     expected: Option<PackageManagerType>,

crates/vp_global_cli/src/shim/dispatch.rs

@@ -661,7 +661,7 @@ async fn resolve_package_manager_tool(
         return Ok(None);
     };
 
-    let resolution = package_manager::resolve_current_for(cwd, Some(expected_type)).await?;
+    let resolution = package_manager::resolve_shim_for(cwd, expected_type).await?;
     let (version, hash) = match resolution {
         Some(resolution) => (resolution.version, resolution.hash),
         None if expected_type == PackageManagerType::Npm => return Ok(None),

docs/guide/env.md

@@ -54,7 +54,9 @@ Package-manager selection uses this priority:
 6. The named package manager's global default version
 7. The named shim's latest release
 
-A selected manager controls only its named shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Alias pairs are `npm`/`npx`, `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The resolved version is cached for one hour and an expired cache remains available when the registry cannot be reached. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release.
+`VP_PACKAGE_MANAGER` selects the manager and version for commands such as `vp install`. Direct package-manager shims ignore this variable and continue to resolve their versions from the session file, project configuration, and family default.
+
+A project selection controls only its named shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Alias pairs are `npm`/`npx`, `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The resolved version is cached for one hour and an expired cache remains available when the registry cannot be reached. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release.
 
 A fresh install uses the split platform layout by default. On Unix, Vite+
 stores managed runtimes and related files in `~/.local/share/vite-plus`. It