fix(ipc): serve getEnv(s) from the spawn's full env context saved in the plan

A command-prefixed env (PREFIXED_ENV=x node tool.mjs) is part of the
spawn's env, but getEnv resolved against the session snapshot only and
answered (unset) — and recorded that wrong value into the post-run
fingerprint.

The plan now saves two env maps per spawn: all_envs (filtered, passed to
the child — unchanged) and full_envs, the planning context's envs overlaid
with the spawn's own additions. Nested expansions already thread prefix
envs into the context, so full_envs picks up enclosing runs' prefixes too
(taskA: PREFIXED_A=a vt run taskB → taskB's getEnv sees PREFIXED_A).
full_envs is serde-skipped: it mirrors the ambient env and is not part of
the plan's identity.

The Recorder and tracked-env validation both use full_envs, keeping record
and lookup symmetric per cache key (prefix envs are in the spawn
fingerprint, so a changed prefix is a different entry).

e2e: fetch_env_sees_command_prefix_env (was failing, now green) and
fetch_env_sees_intermediate_prefix_envs (nested prefix accumulation +
cache-hit validation).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: wan9chi

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

@@ -86,10 +86,6 @@ struct ExecutionContext<'a> {
     /// Workspace root that relative paths in cache entries (inputs, outputs,
     /// archives) are resolved against.
     workspace_root: &'a Arc<AbsolutePath>,
-    /// The session env snapshot the plan was bootstrapped from. Serves IPC
-    /// `getEnv`/`getEnvs` and validates tracked envs at cache lookup — the
-    /// live process env is never re-read during execution.
-    envs: &'a Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
     /// Directory where cache files (db, archives) are stored.
     cache_dir: &'a AbsolutePath,
     /// Public-facing program name (e.g. `vp`), used in user-facing error
@@ -252,7 +248,6 @@ impl ExecutionContext<'_> {
                     spawn_execution,
                     self.cache,
                     self.workspace_root,
-                    self.envs,
                     self.cache_dir,
                     self.program_name,
                     self.fast_fail_token.clone(),
@@ -364,13 +359,17 @@ pub async fn execute_spawn(
     spawn_execution: &SpawnExecution,
     cache: &ExecutionCache,
     workspace_root: &Arc<AbsolutePath>,
-    envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
     cache_dir: &AbsolutePath,
     program_name: &str,
     fast_fail_token: CancellationToken,
     interrupt_token: CancellationToken,
 ) -> SpawnOutcome {
     let cache_metadata = spawn_execution.cache_metadata.as_ref();
+    // The spawn's full env context from the plan (session envs plus prefix
+    // envs of this command and of enclosing nested runs). Resolves IPC
+    // `getEnv`/`getEnvs` and validates tracked envs — the live process env is
+    // never re-read during execution.
+    let envs = &spawn_execution.spawn_command.full_envs;
 
     // 1. Determine cache status FIRST by trying cache hit.
     //    We need to know the status before calling start() so the reporter
@@ -510,11 +509,11 @@ pub async fn execute_spawn(
                     // we abort the execution — tools that rely on IPC would
                     // otherwise silently diverge from the cache.
                     //
-                    // The IPC `getEnv` endpoint serves values from the session
-                    // env snapshot (not the task's filtered `all_envs`), so a
-                    // tool can ask for vars the user never declared and have
+                    // The IPC `getEnv` endpoint serves values from the spawn's
+                    // full env context (not the task's filtered `all_envs`), so
+                    // a tool can ask for vars the user never declared and have
                     // them fingerprinted via the tool's `tracked: true` flag.
-                    // The same snapshot validates these envs at cache lookup.
+                    // The same map validates these envs at cache lookup.
                     match serve(Recorder::new(Arc::clone(envs))) {
                         Ok((envs, ServerHandle { driver, stop_accepting })) => Some(Tracking {
                             input_negative_globs: negatives,
@@ -1073,7 +1072,6 @@ impl Session<'_> {
             reporter: &reporter,
             cache,
             workspace_root: &self.workspace_path,
-            envs: &self.envs,
             cache_dir: &self.cache_path,
             program_name: self.program_name.as_str(),
             fast_fail_token: CancellationToken::new(),

crates/vite_task/src/session/mod.rs

@@ -726,7 +726,6 @@ impl<'a> Session<'a> {
             &spawn_execution,
             cache,
             &self.workspace_path,
-            &self.envs,
             &self.cache_path,
             self.program_name.as_str(),
             tokio_util::sync::CancellationToken::new(),

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

@@ -481,6 +481,7 @@ pub mod test_fixtures {
                         program_path: test_path(),
                         args: Arc::from([]),
                         all_envs: Arc::new(BTreeMap::new()),
+                        full_envs: Arc::new(rustc_hash::FxHashMap::default()),
                         cwd: test_path(),
                     },
                 })),

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

@@ -0,0 +1,18 @@
+import { getEnv } from '@voidzero-dev/vite-task-client';
+import { writeFileSync, mkdirSync } from 'node:fs';
+
+// Reached via `outer-prefixed` (`PREFIXED_A=a vt run inner-prefixed`): the
+// nested run carries PREFIXED_A into the planning context, and our own
+// command (`PREFIXED_B=b node ...`) prefixes PREFIXED_B. getEnv must serve
+// both. Only PREFIXED_B reaches this process's env — PREFIXED_A is
+// undeclared, so the spawn env filters it; the runner still knows it.
+const servedA = getEnv('PREFIXED_A', { tracked: true }) ?? '(unset)';
+const servedB = getEnv('PREFIXED_B', { tracked: true }) ?? '(unset)';
+const ownA = process.env.PREFIXED_A ?? '(unset)';
+const ownB = process.env.PREFIXED_B ?? '(unset)';
+
+mkdirSync('dist', { recursive: true });
+writeFileSync(
+  'dist/out.txt',
+  `served A=${servedA} B=${servedB}\nprocess.env A=${ownA} B=${ownB}\n`,
+);

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

@@ -0,0 +1,12 @@
+import { getEnv } from '@voidzero-dev/vite-task-client';
+import { writeFileSync, mkdirSync } from 'node:fs';
+
+// The task command prefixes `PREFIXED_ENV=from-command` (see vite-task.json),
+// so this process's own env carries that value. `getEnv` must serve the same
+// value: the runner resolves from the spawn's env context (session env
+// overlaid with the command's prefix envs), not the session env alone.
+const served = getEnv('PREFIXED_ENV', { tracked: true }) ?? '(unset)';
+const own = process.env.PREFIXED_ENV ?? '(unset)';
+
+mkdirSync('dist', { recursive: true });
+writeFileSync('dist/out.txt', `served=${served}\nprocess.env=${own}\n`);

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

@@ -172,3 +172,56 @@ steps = [
     ],
   ], comment = "cache miss: envs changed (PROBE_ENV changed)" },
 ]
+
+[[e2e]]
+name = "fetch_env_sees_command_prefix_env"
+comment = """
+A command-prefixed env (`PREFIXED_ENV=from-command node ...`) is part of the
+spawn's env context: the child process sees it in `process.env`, so
+`getEnv('PREFIXED_ENV')` must serve the same value. Today the runner resolves
+`getEnv` against the session env snapshot only, so it answers `(unset)` while
+the process env says `from-command`.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-prefixed-env",
+  ], comment = "tool asks the runner for an env the command prefix sets" },
+  { argv = [
+    "vtt",
+    "print-file",
+    "dist/out.txt",
+  ], comment = "served value must match the process env value" },
+]
+
+[[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 — the
+nested expansion threads PREFIXED_A into the inner spawn's env context even
+though the (undeclared) var never reaches the inner process env. The second
+run validates the tracked values against the same plan-derived context and
+hits the cache.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "outer-prefixed",
+  ], comment = "outer prefix env reaches the inner tool via the runner" },
+  { argv = [
+    "vtt",
+    "print-file",
+    "dist/out.txt",
+  ], comment = "both prefix envs served; only the inner one is in process.env" },
+  { argv = [
+    "vt",
+    "run",
+    "outer-prefixed",
+  ], comment = "cache hit: tracked values validate against the plan's env context" },
+]

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

@@ -0,0 +1,24 @@
+# fetch_env_sees_command_prefix_env
+
+A command-prefixed env (`PREFIXED_ENV=from-command node ...`) is part of the
+spawn's env context: the child process sees it in `process.env`, so
+`getEnv('PREFIXED_ENV')` must serve the same value. Today the runner resolves
+`getEnv` against the session env snapshot only, so it answers `(unset)` while
+the process env says `from-command`.
+
+## `vt run fetch-prefixed-env`
+
+tool asks the runner for an env the command prefix sets
+
+```
+$ PREFIXED_ENV=from-command node scripts/fetch_prefixed_env.mjs
+```
+
+## `vtt print-file dist/out.txt`
+
+served value must match the process env value
+
+```
+served=from-command
+process.env=from-command
+```

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

@@ -0,0 +1,37 @@
+# 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 — the
+nested expansion threads PREFIXED_A into the inner spawn's env context even
+though the (undeclared) var never reaches the inner process env. The second
+run validates the tracked values against the same plan-derived context and
+hits the cache.
+
+## `vt run outer-prefixed`
+
+outer prefix env reaches the inner tool via the runner
+
+```
+$ PREFIXED_B=b node scripts/fetch_intermediate_envs.mjs
+```
+
+## `vtt print-file dist/out.txt`
+
+both prefix envs served; only the inner one is in process.env
+
+```
+served A=a B=b
+process.env A=(unset) B=b
+```
+
+## `vt run outer-prefixed`
+
+cache hit: tracked values validate against the plan's env context
+
+```
+$ PREFIXED_B=b node scripts/fetch_intermediate_envs.mjs ◉ cache hit, replaying
+
+---
+vt run: cache hit.
+```

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

@@ -19,6 +19,18 @@
     "fetch-envs": {
       "command": "node scripts/fetch_envs.mjs",
       "cache": true
+    },
+    "fetch-prefixed-env": {
+      "command": "PREFIXED_ENV=from-command node scripts/fetch_prefixed_env.mjs",
+      "cache": true
+    },
+    "outer-prefixed": {
+      "command": "PREFIXED_A=a vt run inner-prefixed",
+      "cache": true
+    },
+    "inner-prefixed": {
+      "command": "PREFIXED_B=b node scripts/fetch_intermediate_envs.mjs",
+      "cache": true
     }
   }
 }

crates/vite_task_client_napi/src/lib.rs

@@ -120,6 +120,10 @@ impl RunnerClient {
 /// IPC env is missing or the connection fails.
 #[napi]
 pub fn load() -> Result<RunnerClient> {
+    #[expect(
+        clippy::disallowed_methods,
+        reason = "client load needs the live process env to discover runner IPC connection vars"
+    )]
     let client = Client::from_envs(std::env::vars_os())
         .map_err(|err| {
             err_string(vite_str::format!("vp run client: failed to connect to runner IPC: {err}"))