fix(plan): serve runner getEnv from unfiltered env context (#447)

## Motivation

Runner-served `getEnv` values need to match the command context that planning and execution use, including command-prefix envs and enclosing nested `vp run` prefix envs. Serving only the cache-filtered child env hides undeclared prefix values from runner-aware tools.

## Scope

Build on the `spawn_envs` naming cleanup by storing the unfiltered command env context on `CacheMetadata` for cached executions, then serve runner `getEnv` from that context. `SpawnCommand::spawn_envs` remains focused on the actual child process environment.

This PR intentionally does not add cache fingerprinting for runner-served env reads. That is handled by the next PR in the stack. The e2e fixture now uses one generic `fetch_env.mjs <NAME> [...]` helper and compares runner-served values with `process.env` for undeclared envs, command-prefix envs, and nested prefix envs.

## Verification

- `cargo test -p vite_task_bin --test e2e_snapshots fetch_env -- --ignored`

Author: wan9chi

crates/vite_task/src/session/execute/mod.rs

@@ -18,7 +18,6 @@ use std::{
 };
 
 use futures_util::future::LocalBoxFuture;
-use rustc_hash::FxHashMap;
 use tokio_util::sync::CancellationToken;
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_task_ipc_shared::NODE_CLIENT_PATH_ENV_NAME;
@@ -157,7 +156,6 @@ impl<'a> ExecutionMode<'a> {
         cache_metadata: Option<&'a CacheMetadata>,
         stdio_config: StdioConfig,
         globbed_inputs: BTreeMap<RelativePathBuf, u64>,
-        envs: &BTreeMap<Arc<OsStr>, Arc<OsStr>>,
     ) -> Result<Self, ExecutionError> {
         let Some(metadata) = cache_metadata else {
             return Ok(Self::Uncached {
@@ -184,10 +182,9 @@ impl<'a> ExecutionMode<'a> {
         // Bind runner IPC for every cached task. The merged cache-control API
         // (`disableCache`) must work even when a task uses explicit inputs and
         // therefore does not need fspy auto-input inference.
-        let server_envs: FxHashMap<Arc<OsStr>, Arc<OsStr>> =
-            envs.iter().map(|(name, value)| (Arc::clone(name), Arc::clone(value))).collect();
         let (ipc_envs, ServerHandle { driver, stop_accepting }) =
-            serve(Recorder::new(Arc::new(server_envs))).map_err(ExecutionError::IpcServerBind)?;
+            serve(Recorder::new(Arc::clone(&metadata.unfiltered_envs)))
+                .map_err(ExecutionError::IpcServerBind)?;
         let tracking =
             Tracking { fspy, ipc_envs: ipc_envs.collect(), ipc_server_fut: driver, stop_accepting };
 
@@ -409,16 +406,8 @@ async fn run(
     };
 
     // 4. Fold the cache/fspy/stdio decisions into the typed mode.
-    let mut mode = ExecutionMode::build(
-        cache_metadata,
-        stdio_config,
-        globbed_inputs,
-        // TODO(env-track): A later PR in this stack replaces this child env
-        // map with the full planned env context so IPC can serve envs even
-        // when they were not declared in `env` or `untrackedEnv`.
-        &spawn_execution.spawn_command.spawn_envs,
-    )
-    .map_err(Report::failed)?;
+    let mut mode = ExecutionMode::build(cache_metadata, stdio_config, globbed_inputs)
+        .map_err(Report::failed)?;
 
     // Measure end-to-end duration here — spawn() doesn't track time.
     let start = Instant::now();

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/fetch_env.mjs

@@ -1,5 +1,13 @@
 import { getEnv } from '@voidzero-dev/vite-task-client';
 
-const value = getEnv('PROBE_ENV') ?? '(unset)';
+const names = process.argv.slice(2);
 
-console.log('PROBE_ENV=' + value);
+if (names.length === 0) {
+  throw new Error('usage: fetch_env.mjs <NAME> [...]');
+}
+
+const served = names.map((name) => `${name}=${getEnv(name) ?? '(unset)'}`);
+const own = names.map((name) => `${name}=${process.env[name] ?? '(unset)'}`);
+
+console.log(`served ${served.join(' ')}`);
+console.log(`process.env ${own.join(' ')}`);

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml

@@ -48,20 +48,48 @@ steps = [
 ]
 
 [[e2e]]
-name = "fetch_env_reads_declared_env"
+name = "fetch_env_reads_undeclared_env"
 comment = """
-Exercises `getEnv(name)`: the tool asks the runner for a declared env var and prints the served value. This verifies the round-trip IPC behavior before any runner-reported env is added to the cache fingerprint.
+Exercises `getEnv(name)`: the tool asks the runner for an env var that is not declared in the task's `env` list. This verifies runner-served envs resolve from the unfiltered spawn env context while the child process env remains cache-filtered.
 """
 ignore = true
 steps = [
   { argv = [
     "vt",
     "run",
-    "fetch-env-declared",
+    "fetch-env",
   ], envs = [
     [
       "PROBE_ENV",
       "served",
     ],
-  ], comment = "runner serves PROBE_ENV from the spawned task env map" },
+  ], comment = "runner serves undeclared PROBE_ENV from the unfiltered env context" },
+]
+
+[[e2e]]
+name = "fetch_env_sees_command_prefix_env"
+comment = """
+A command-prefixed env (`PREFIXED_ENV=from-command node ...`) is part of the spawn's full env context. `getEnv('PREFIXED_ENV')` and `process.env.PREFIXED_ENV` must both see the command prefix value.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-prefixed-env",
+  ], comment = "tool asks the runner for an env the command prefix sets" },
+]
+
+[[e2e]]
+name = "fetch_env_sees_intermediate_prefix_envs"
+comment = """
+Prefix envs accumulate through nested runs: `outer-prefixed` is `PREFIXED_A=a vt run inner-prefixed`, and `inner-prefixed` is `PREFIXED_B=b node ...`. The inner tool's `getEnv` must see both through the runner's env context, while `process.env` only sees the direct child prefix.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "outer-prefixed",
+  ], comment = "outer prefix env reaches the inner tool via the runner" },
 ]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_reads_declared_env.md

@@ -0,0 +1,13 @@
+# fetch_env_reads_undeclared_env
+
+Exercises `getEnv(name)`: the tool asks the runner for an env var that is not declared in the task's `env` list. This verifies runner-served envs resolve from the unfiltered spawn env context while the child process env remains cache-filtered.
+
+## `PROBE_ENV=served vt run fetch-env`
+
+runner serves undeclared PROBE_ENV from the unfiltered env context
+
+```
+$ node scripts/fetch_env.mjs PROBE_ENV
+served PROBE_ENV=served
+process.env PROBE_ENV=(unset)
+```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_reads_undeclared_env.md

@@ -0,0 +1,13 @@
+# fetch_env_sees_command_prefix_env
+
+A command-prefixed env (`PREFIXED_ENV=from-command node ...`) is part of the spawn's full env context. `getEnv('PREFIXED_ENV')` and `process.env.PREFIXED_ENV` must both see the command prefix value.
+
+## `vt run fetch-prefixed-env`
+
+tool asks the runner for an env the command prefix sets
+
+```
+$ PREFIXED_ENV=from-command node scripts/fetch_env.mjs PREFIXED_ENV
+served PREFIXED_ENV=from-command
+process.env PREFIXED_ENV=from-command
+```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_sees_command_prefix_env.md

@@ -0,0 +1,13 @@
+# fetch_env_sees_intermediate_prefix_envs
+
+Prefix envs accumulate through nested runs: `outer-prefixed` is `PREFIXED_A=a vt run inner-prefixed`, and `inner-prefixed` is `PREFIXED_B=b node ...`. The inner tool's `getEnv` must see both through the runner's env context, while `process.env` only sees the direct child prefix.
+
+## `vt run outer-prefixed`
+
+outer prefix env reaches the inner tool via the runner
+
+```
+$ PREFIXED_B=b node scripts/fetch_env.mjs PREFIXED_A PREFIXED_B
+served PREFIXED_A=a PREFIXED_B=b
+process.env PREFIXED_A=(unset) PREFIXED_B=b
+```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_sees_intermediate_prefix_envs.md

@@ -9,10 +9,20 @@
       "input": [],
       "cache": true
     },
-    "fetch-env-declared": {
-      "command": "node scripts/fetch_env.mjs",
-      // TODO(env-track): Remove this explicit env declaration down the stack and update the e2e name once runner-tracked env reads cover it.
-      "env": ["PROBE_ENV"],
+    "fetch-env": {
+      "command": "node scripts/fetch_env.mjs PROBE_ENV",
+      "cache": true
+    },
+    "fetch-prefixed-env": {
+      "command": "PREFIXED_ENV=from-command node scripts/fetch_env.mjs PREFIXED_ENV",
+      "cache": true
+    },
+    "outer-prefixed": {
+      "command": "PREFIXED_A=a vt run inner-prefixed",
+      "cache": true
+    },
+    "inner-prefixed": {
+      "command": "PREFIXED_B=b node scripts/fetch_env.mjs PREFIXED_A PREFIXED_B",
       "cache": true
     }
   }

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json

@@ -1,5 +1,6 @@
-use std::sync::Arc;
+use std::{ffi::OsStr, sync::Arc};
 
+use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use vite_path::RelativePathBuf;
 use vite_str::{self, Str};
@@ -52,6 +53,16 @@ pub struct CacheMetadata {
     /// Resolved output configuration for cache restoration.
     /// Used at execution time to determine what output files to archive.
     pub output_config: ResolvedGlobConfig,
+
+    /// The unfiltered env context for runner-aware APIs. This is the planning
+    /// context's envs before spawn-env filtering, including command prefix envs
+    /// from this command and enclosing nested `vp run` expansions.
+    ///
+    /// It is not passed to the spawned process; that remains
+    /// `SpawnCommand::spawn_envs`. It is skipped in serialized plans because it
+    /// mirrors the ambient environment and would make snapshots noisy.
+    #[serde(skip)]
+    pub unfiltered_envs: Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
 }
 
 /// Fingerprint for spawn execution that affects caching.

crates/vite_task_plan/src/cache_metadata.rs

@@ -143,11 +143,11 @@ async fn plan_task_as_execution_node(
 
                 // This command's env context: extend the planning context with
                 // the command's prefix envs (`FOO=1 tool ...`). Everything that
-                // interprets the command reads this one context — program
-                // lookup, plan-request callbacks, and nested-run planning. The
-                // per-and-item duplicate above scopes the extension to this
-                // command, matching shell semantics (`FOO=1 a && b` does not
-                // set `FOO` for `b`).
+                // interprets the command reads this one context: program
+                // lookup, plan-request callbacks, nested-run planning, and
+                // cached execution metadata. The per-and-item duplicate
+                // above scopes the extension to this command, matching shell
+                // semantics (`FOO=1 a && b` does not set `FOO` for `b`).
                 context.add_envs(and_item.envs.iter());
 
                 let mut args = and_item.args;
@@ -673,6 +673,7 @@ fn plan_spawn_execution(
                 execution_cache_key,
                 input_config: cache_config.input_config.clone(),
                 output_config: cache_config.output_config.clone(),
+                unfiltered_envs: Arc::clone(envs),
             });
         }
     }