fix(cache): resolve and validate tracked envs from the session env snapshot

The IPC Recorder's env map and PostRunFingerprint::validate both read the
live process env (std::env::vars_os / var_os). Tasks' envs come from the
plan; std::env::vars_os is only meant to bootstrap the session snapshot
(Session.envs) at init. Thread that snapshot through ExecutionContext /
execute_spawn into Recorder::new (now Arc-shared) and through
ExecutionCache::try_hit into validate, so getEnv/getEnvs and the
tracked-env lookup validation resolve against the same map the plan was
built from — and tests can inject envs via Session::init_with.

Document the rule in CLAUDE.md (Code Constraints → Environment Variables).

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

Author: wan9chi

CLAUDE.md

@@ -140,6 +140,10 @@ Enforced by `.clippy.toml`:
 - Only convert to std paths when interfacing with std library functions
 - Add necessary methods in `vite_path` instead of falling back to std path types
 
+### Environment Variables
+
+`std::env::vars_os` is read exactly once — in `Session::init` — to bootstrap the session env snapshot (`Session.envs`). Everything downstream (planning, spawn env resolution, IPC `getEnv`/`getEnvs`, cache fingerprint validation) must use that snapshot or the plan's resolved env maps, never re-read the live process env. This keeps a run's behavior consistent with its plan and lets tests inject envs via `Session::init_with`.
+
 ### Cross-Platform Requirements
 
 All code must work on both Unix and Windows without platform skipping:

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

@@ -3,7 +3,9 @@
 pub mod archive;
 pub mod display;
 
-use std::{collections::BTreeMap, fmt::Display, fs::File, io::Write, sync::Arc, time::Duration};
+use std::{
+    collections::BTreeMap, ffi::OsStr, fmt::Display, fs::File, io::Write, sync::Arc, time::Duration,
+};
 
 // Re-export display functions for convenience
 pub use display::format_cache_status_inline;
@@ -12,6 +14,7 @@ pub use display::{
     format_spawn_change,
 };
 use rusqlite::{Connection, OptionalExtension as _};
+use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use tokio::sync::Mutex;
 use vite_path::{AbsolutePath, RelativePathBuf};
@@ -329,12 +332,16 @@ impl ExecutionCache {
 
     /// Try to hit cache by looking up the cache entry key and validating inputs.
     /// Returns `Ok(Ok(cache_value))` on cache hit, `Ok(Err(cache_miss))` on miss.
+    ///
+    /// `envs` is the session env snapshot the run's plan was bootstrapped from;
+    /// tracked-env validation resolves against it, never the live process env.
     #[tracing::instrument(level = "debug", skip_all)]
     pub async fn try_hit(
         &self,
         cache_metadata: &CacheMetadata,
         globbed_inputs: &BTreeMap<RelativePathBuf, u64>,
         workspace_root: &AbsolutePath,
+        envs: &FxHashMap<Arc<OsStr>, Arc<OsStr>>,
     ) -> anyhow::Result<Result<CacheEntryValue, CacheMiss>> {
         let spawn_fingerprint = &cache_metadata.spawn_fingerprint;
         let execution_cache_key = &cache_metadata.execution_cache_key;
@@ -351,7 +358,9 @@ impl ExecutionCache {
             }
 
             // Validate post-run fingerprint (inferred inputs + tracked envs)
-            if let Some(mismatch) = cache_value.post_run_fingerprint.validate(workspace_root)? {
+            if let Some(mismatch) =
+                cache_value.post_run_fingerprint.validate(workspace_root, envs)?
+            {
                 return Ok(Err(CacheMiss::FingerprintMismatch(mismatch.into())));
             }
             // Associate the execution key to the cache entry key if not already,

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

@@ -5,12 +5,14 @@
 
 use std::{
     collections::BTreeMap,
+    ffi::OsStr,
     fs::File,
     io::{self, BufRead},
     sync::Arc,
 };
 
 use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
+use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_str::Str;
@@ -38,13 +40,13 @@ pub struct PostRunFingerprint {
     /// Env vars observed via runner-aware IPC `getEnv` with `tracked: true`.
     /// Key is the env name; value is the env value at execution time (or
     /// `None` if unset). Validated at cache lookup by comparing against the
-    /// current parent env.
+    /// session env snapshot.
     pub tracked_envs: BTreeMap<Str, Option<Str>>,
 
     /// Glob-pattern env queries (`getEnvs`) made with `tracked: true`.
     /// Outer key is the glob pattern, inner map is the match-set at
     /// execution time (name → value). Validated at cache lookup by
-    /// re-matching against the current parent env and comparing the
+    /// re-matching against the session env snapshot and comparing the
     /// resulting set.
     pub tracked_env_globs: BTreeMap<Str, BTreeMap<Str, Str>>,
 }
@@ -125,10 +127,19 @@ impl PostRunFingerprint {
         Ok(Self { inferred_inputs, tracked_envs, tracked_env_globs })
     }
 
-    /// Validates the fingerprint against current filesystem and env state.
-    /// Returns `Some(mismatch)` on the first divergence, `None` if all valid.
+    /// Validates the fingerprint against the current filesystem state and the
+    /// session env snapshot. Returns `Some(mismatch)` on the first divergence,
+    /// `None` if all valid.
+    ///
+    /// `envs` must be the same env map the run's plan was bootstrapped from
+    /// (`Session.envs`) — the map that served `getEnv`/`getEnvs` at record
+    /// time — never a fresh read of the process env.
     #[tracing::instrument(level = "debug", skip_all, name = "validate_post_run_fingerprint")]
-    pub fn validate(&self, base_dir: &AbsolutePath) -> anyhow::Result<Option<PostRunMismatch>> {
+    pub fn validate(
+        &self,
+        base_dir: &AbsolutePath,
+        envs: &FxHashMap<Arc<OsStr>, Arc<OsStr>>,
+    ) -> anyhow::Result<Option<PostRunMismatch>> {
         let input_mismatch = self.inferred_inputs.par_iter().find_map_any(
             |(input_relative_path, path_fingerprint)| {
                 let input_full_path = Arc::<AbsolutePath>::from(base_dir.join(input_relative_path));
@@ -162,22 +173,22 @@ impl PostRunFingerprint {
             return result.map(Some);
         }
 
-        // Validate tracked envs against the current parent env.
+        // Validate tracked envs against the session env snapshot.
         for (name, stored_value) in &self.tracked_envs {
             let current_value =
-                std::env::var_os(name.as_str()).and_then(|v| v.to_str().map(Str::from));
+                envs.get(OsStr::new(name.as_str())).and_then(|v| v.to_str().map(Str::from));
             if let Some(mismatch) =
                 EnvMismatch::compare(name, stored_value.as_ref(), current_value.as_ref())
             {
                 return Ok(Some(PostRunMismatch::TrackedEnvChanged(mismatch)));
             }
         }
 
-        // Validate tracked env globs: re-enumerate the parent env for each
-        // pattern and report the first entry that diverges from the stored
-        // match-set.
+        // Validate tracked env globs: re-expand each pattern over the session
+        // env snapshot and report the first entry that diverges from the
+        // stored match-set.
         for (pattern, stored_matches) in &self.tracked_env_globs {
-            let current_matches = match_env_glob(pattern.as_str())?;
+            let current_matches = match_env_glob(pattern.as_str(), envs)?;
             if let Some(mismatch) = first_env_glob_mismatch(stored_matches, &current_matches) {
                 return Ok(Some(PostRunMismatch::TrackedEnvGlobChanged {
                     pattern: pattern.clone(),
@@ -190,18 +201,22 @@ impl PostRunFingerprint {
     }
 }
 
-/// Build the current match-set for `pattern` by enumerating
-/// `std::env::vars_os()` and keeping UTF-8 names whose representation matches
-/// the glob. Mirrors the server-side match (see
-/// `vite_task_server::Recorder::get_envs`).
-fn match_env_glob(pattern: &str) -> anyhow::Result<BTreeMap<Str, Str>> {
+/// Build the current match-set for `pattern` by enumerating the given env
+/// snapshot and keeping UTF-8 names whose representation matches the glob.
+/// Mirrors the server-side match (see `vite_task_server::Recorder::get_envs`),
+/// which resolved against the same map at record time.
+fn match_env_glob(
+    pattern: &str,
+    envs: &FxHashMap<Arc<OsStr>, Arc<OsStr>>,
+) -> anyhow::Result<BTreeMap<Str, Str>> {
     let glob = vite_glob::env::EnvGlob::new(pattern)?;
-    Ok(std::env::vars_os()
+    Ok(envs
+        .iter()
         .filter_map(|(name, value)| {
-            let name_str = name.to_str()?.to_owned();
-            let value_str = value.to_str()?.to_owned();
-            if glob.is_match(name_str.as_str()) {
-                Some((Str::from(name_str.as_str()), Str::from(value_str.as_str())))
+            let name_str = name.to_str()?;
+            let value_str = value.to_str()?;
+            if glob.is_match(name_str) {
+                Some((Str::from(name_str), Str::from(value_str)))
             } else {
                 None
             }

crates/vite_task/src/session/mod.rs

@@ -726,6 +726,7 @@ 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(),

docs/runner-task-ipc/index.md

@@ -20,7 +20,7 @@ Report information from the tools to the runner, to help runner cache results wi
 Workflow:
 
 1. For each spawn execution, `vite_task` starts an IPC server via `vite_task_server::serve` and passes the server's connection info plus the path to a materialized node addon into the child's env.
-2. The task process loads the addon through `@voidzero-dev/vite-task-client` and reports back over IPC: which reads/writes to ignore, which envs it needs (returned by the runner from the spawn's resolved env map), and whether to disable caching.
+2. The task process loads the addon through `@voidzero-dev/vite-task-client` and reports back over IPC: which reads/writes to ignore, which envs it needs (resolved by the runner from the session env snapshot its plan was bootstrapped from), and whether to disable caching.
 3. When the task exits, the server drains and hands its collected reports back to `vite_task`, which feeds them into the cache layer.
 
 Crate / package responsibilities: