feat(cache): fingerprint tracked getEnv reads

Motivation:
Once tools can read env values from the runner, cached tasks must remember tracked getEnv reads or a later run can replay stale output after the env changes.

Scope:
Make the getEnv tracked option meaningful, record served single-env values in IPC reports, store tracked getEnv values in the post-run fingerprint, validate them during cache lookup, and render env-specific cache miss messages. This PR intentionally does not implement getEnvs or env glob match-set tracking.

Verification:
- cargo test -p vite_task_server --test integration
- UPDATE_SNAPSHOTS=1 cargo test -p vite_task_bin --test e2e_snapshots fetch_env_tracked_invalidates_on_change -- --ignored
- UPDATE_SNAPSHOTS=1 cargo test -p vite_task_bin --test e2e_snapshots fetch_env_tracks_with_explicit_inputs -- --ignored
- cargo test -p vite_task_bin --test e2e_snapshots fetch_env_tracked_invalidates_on_change -- --ignored
- cargo test -p vite_task_bin --test e2e_snapshots fetch_env_tracks_with_explicit_inputs -- --ignored

Author: wan9chi

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- **Added** Runner-aware `getEnv` reads can now participate in task cache fingerprints, so changing a tool-served env value invalidates the cache and names the env var in the miss message.
 - **Added** Runner-aware tools can now opt the current task run out of caching through the new IPC channel; Vite dev server integration uses this automatically ([#441](https://github.com/voidzero-dev/vite-task/pull/441))
 - **Fixed** Prefix environment assignments like `PATH=... command` now affect executable lookup during task planning, so tools provided only by the prefixed `PATH` can be resolved correctly ([#440](https://github.com/voidzero-dev/vite-task/pull/440))
 - **Changed** Cache misses caused by a tracked env var now name the env var inline, for example `cache miss: env 'NODE_ENV' changed`, instead of the generic `envs changed` message ([#438](https://github.com/voidzero-dev/vite-task/pull/438))

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

@@ -195,6 +195,9 @@ pub fn format_cache_status_inline(cache_status: &CacheStatus) -> Option<Str> {
                 FingerprintMismatch::InputChanged { kind, path } => {
                     format_input_change_str(*kind, path.as_str())
                 }
+                FingerprintMismatch::TrackedEnvChanged(mismatch) => {
+                    format_env_changed_inline(&[mismatch.name()])
+                }
             };
             Some(vite_str::format!("○ cache miss: {reason}, executing"))
         }

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};
@@ -165,6 +168,23 @@ impl EnvMismatch {
             }
         }
     }
+
+    /// Compare a stored env value against the current one, returning the
+    /// mismatch if they differ. `None` on either side means the env is unset
+    /// there; two unset or two equal values are not a mismatch.
+    #[must_use]
+    pub fn compare(name: &Str, stored: Option<&Str>, current: Option<&Str>) -> Option<Self> {
+        match (stored, current) {
+            (None, Some(value)) => Some(Self::Added { name: name.clone(), value: value.clone() }),
+            (Some(value), None) => Some(Self::Removed { name: name.clone(), value: value.clone() }),
+            (Some(old_value), Some(new_value)) if old_value != new_value => Some(Self::Changed {
+                name: name.clone(),
+                old_value: old_value.clone(),
+                new_value: new_value.clone(),
+            }),
+            _ => None,
+        }
+    }
 }
 
 impl Display for EnvMismatch {
@@ -198,23 +218,16 @@ pub enum FingerprintMismatch {
         kind: InputChangeKind,
         path: RelativePathBuf,
     },
+    /// A runner-aware tool-tracked env var changed between runs.
+    TrackedEnvChanged(EnvMismatch),
 }
 
-impl Display for FingerprintMismatch {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::SpawnFingerprint { old, new } => {
-                write!(f, "Spawn fingerprint changed: old={old:?}, new={new:?}")
-            }
-            Self::InputConfig => {
-                write!(f, "input configuration changed")
-            }
-            Self::OutputConfig => {
-                write!(f, "output configuration changed")
-            }
-            Self::InputChanged { kind, path } => {
-                write!(f, "{}", display::format_input_change_str(*kind, path.as_str()))
-            }
+impl From<crate::session::execute::fingerprint::PostRunMismatch> for FingerprintMismatch {
+    fn from(mismatch: crate::session::execute::fingerprint::PostRunMismatch) -> Self {
+        use crate::session::execute::fingerprint::PostRunMismatch;
+        match mismatch {
+            PostRunMismatch::InputChanged { kind, path } => Self::InputChanged { kind, path },
+            PostRunMismatch::TrackedEnvChanged(mismatch) => Self::TrackedEnvChanged(mismatch),
         }
     }
 }
@@ -240,7 +253,7 @@ pub fn split_path(path: &str) -> (Option<&str>, &str) {
 /// its own cache warm across branch switches, and a cache from a different
 /// version is simply ignored (it lives in a directory this build never looks
 /// at) rather than aborting the run. Bumping the version starts a fresh cache.
-const CACHE_SCHEMA_VERSION: u32 = 13;
+const CACHE_SCHEMA_VERSION: u32 = 14;
 
 /// Name of the per-version subdirectory (e.g. `v13`) under the task-cache
 /// directory that holds the database and output archives for the current
@@ -292,6 +305,7 @@ impl ExecutionCache {
         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;
@@ -307,11 +321,11 @@ impl ExecutionCache {
                 return Ok(Err(CacheMiss::FingerprintMismatch(mismatch)));
             }
 
-            // Validate post-run fingerprint (inferred inputs from fspy)
-            if let Some((kind, path)) = cache_value.post_run_fingerprint.validate(workspace_root)? {
-                return Ok(Err(CacheMiss::FingerprintMismatch(
-                    FingerprintMismatch::InputChanged { kind, path },
-                )));
+            // Validate post-run fingerprint (inferred inputs + tracked envs)
+            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,
             // so that next time we can find it and report what changed

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

@@ -1,7 +1,7 @@
 //! Post-run cache update: decide whether a finished spawn may be cached and,
 //! if so, store its fingerprint, captured output, and output archive.
 
-use std::{sync::Arc, time::Duration};
+use std::{collections::BTreeMap, sync::Arc, time::Duration};
 
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_str::Str;
@@ -97,13 +97,19 @@ pub(super) async fn update_cache(
         return (CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::FspyUnsupported), None);
     }
 
+    // Collect tool-reported tracked envs for the post-run fingerprint. Env
+    // names that the user already declared are skipped because their values
+    // are already part of the spawn fingerprint.
+    let tracked_envs = reports.map(|r| collect_tracked_envs(r, metadata)).unwrap_or_default();
+
     // Paths already in globbed_inputs are skipped: the overlap check above
     // guarantees no input modification, so the prerun hash is the correct
     // post-exec hash.
     let empty_path_reads = HashMap::default();
     let path_reads = fspy_outcome.as_ref().map_or(&empty_path_reads, |o| &o.path_reads);
     let post_run_fingerprint =
-        match PostRunFingerprint::create(path_reads, workspace_root, &globbed_inputs) {
+        match PostRunFingerprint::create(path_reads, workspace_root, &globbed_inputs, tracked_envs)
+        {
             Ok(fingerprint) => fingerprint,
             Err(err) => {
                 return (
@@ -166,6 +172,26 @@ fn observe_fspy(
     }
 }
 
+/// Select tool-reported env records to embed in the post-run fingerprint.
+/// Only `tracked: true` records are included, and names that the user already
+/// declared as fingerprinted are skipped.
+fn collect_tracked_envs(reports: &Reports, metadata: &CacheMetadata) -> BTreeMap<Str, Option<Str>> {
+    let fingerprinted = &metadata.spawn_fingerprint.env_fingerprints().fingerprinted_envs;
+    reports
+        .env_records
+        .iter()
+        .filter(|(_, record)| record.tracked)
+        .filter_map(|(name, record)| {
+            let name_str = name.to_str()?;
+            if fingerprinted.contains_key(name_str) {
+                return None;
+            }
+            let value = record.value.as_ref().and_then(|value| value.to_str().map(Str::from));
+            Some((Str::from(name_str), value))
+        })
+        .collect()
+}
+
 /// Collect output files matching the configured globs and create a tar.zst
 /// archive in the cache directory.
 ///

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

@@ -5,18 +5,23 @@
 
 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;
 use wincode::{SchemaRead, SchemaWrite};
 
-use crate::{collections::HashMap, session::cache::InputChangeKind};
+use crate::{
+    collections::HashMap,
+    session::cache::{EnvMismatch, InputChangeKind},
+};
 
 /// Path read access info
 #[derive(Debug, Clone, Copy)]
@@ -31,6 +36,21 @@ pub struct PostRunFingerprint {
     /// Paths inferred from fspy during execution with their content fingerprints.
     /// Only populated when `input_config.includes_auto` is true.
     pub inferred_inputs: HashMap<RelativePathBuf, PathFingerprint>,
+
+    /// 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 against the same plan env
+    /// context that served the original request.
+    pub tracked_envs: BTreeMap<Str, Option<Str>>,
+}
+
+/// A mismatch between the stored post-run fingerprint and the current state.
+#[derive(Debug, Clone)]
+pub enum PostRunMismatch {
+    /// An inferred input file or directory changed.
+    InputChanged { kind: InputChangeKind, path: RelativePathBuf },
+    /// A tool-tracked env var changed value, appeared, or disappeared.
+    TrackedEnvChanged(EnvMismatch),
 }
 
 /// Fingerprint for a single path (file or directory)
@@ -69,11 +89,13 @@ impl PostRunFingerprint {
     /// * `inferred_path_reads` - Map of paths that were read during execution (from fspy)
     /// * `base_dir` - Workspace root for resolving relative paths
     /// * `globbed_inputs` - Prerun glob fingerprint; paths here are skipped
+    /// * `tracked_envs` - Tool-requested env vars (name -> value), validated on lookup
     #[tracing::instrument(level = "debug", skip_all, name = "create_post_run_fingerprint")]
     pub fn create(
         inferred_path_reads: &HashMap<RelativePathBuf, PathRead>,
         base_dir: &AbsolutePath,
         globbed_inputs: &BTreeMap<RelativePathBuf, u64>,
+        tracked_envs: BTreeMap<Str, Option<Str>>,
     ) -> anyhow::Result<Self> {
         let inferred_inputs = inferred_path_reads
             .par_iter()
@@ -85,16 +107,17 @@ impl PostRunFingerprint {
             })
             .collect::<anyhow::Result<HashMap<_, _>>>()?;
 
-        Ok(Self { inferred_inputs })
+        Ok(Self { inferred_inputs, tracked_envs })
     }
 
-    /// Validates the fingerprint against current filesystem state.
-    /// Returns `Some((kind, path))` if an input changed, `None` if all valid.
+    /// Validates the fingerprint against current filesystem state and env
+    /// context. Returns `Some(mismatch)` if anything changed, `None` if all valid.
     #[tracing::instrument(level = "debug", skip_all, name = "validate_post_run_fingerprint")]
     pub fn validate(
         &self,
         base_dir: &AbsolutePath,
-    ) -> anyhow::Result<Option<(InputChangeKind, RelativePathBuf)>> {
+        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));
@@ -120,11 +143,25 @@ impl PostRunFingerprint {
                     } else {
                         input_relative_path.clone()
                     };
-                    Some(Ok((kind, path)))
+                    Some(Ok(PostRunMismatch::InputChanged { kind, path }))
                 }
             },
         );
-        input_mismatch.transpose()
+        if let Some(result) = input_mismatch {
+            return result.map(Some);
+        }
+
+        for (name, stored_value) in &self.tracked_envs {
+            let current_value =
+                envs.get(OsStr::new(name.as_str())).and_then(|value| value.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)));
+            }
+        }
+
+        Ok(None)
     }
 }
 

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

@@ -531,7 +531,10 @@ async fn lookup_cache(
         Report::failed(ExecutionError::Cache { kind: CacheErrorKind::Lookup, source: err })
     })?;
 
-    match cache.try_hit(cache_metadata, &globbed_inputs, workspace_root).await {
+    match cache
+        .try_hit(cache_metadata, &globbed_inputs, workspace_root, &cache_metadata.unfiltered_envs)
+        .await
+    {
         Ok(Ok(cached)) => Ok(CacheLookup::Hit(cached)),
         Ok(Err(miss)) => Ok(CacheLookup::Miss { miss, globbed_inputs }),
         Err(err) => {

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

@@ -17,7 +17,7 @@ use vite_str::Str;
 use super::{CACHE_MISS_STYLE, COMMAND_STYLE, ColorizeExt};
 use crate::session::{
     cache::{
-        CacheMiss, FingerprintMismatch, InputChangeKind, SpawnFingerprintChange,
+        CacheMiss, EnvMismatch, FingerprintMismatch, InputChangeKind, SpawnFingerprintChange,
         detect_spawn_fingerprint_changes, format_input_change_str, format_spawn_change,
     },
     event::{
@@ -135,6 +135,8 @@ pub enum SavedCacheMissReason {
     ConfigChanged,
     /// An input file or folder changed.
     InputChanged { kind: InputChangeKind, path: Str },
+    /// A runner-aware tool reported a tracked env var that changed between runs.
+    TrackedEnvChanged(EnvMismatch),
 }
 
 /// An execution error, serializable for persistence.
@@ -278,6 +280,9 @@ impl SavedCacheMissReason {
                 FingerprintMismatch::InputChanged { kind, path } => {
                     Self::InputChanged { kind: *kind, path: Str::from(path.as_str()) }
                 }
+                FingerprintMismatch::TrackedEnvChanged(mismatch) => {
+                    Self::TrackedEnvChanged(mismatch.clone())
+                }
             },
         }
     }
@@ -567,6 +572,9 @@ impl TaskResult {
                         let desc = format_input_change_str(*kind, path.as_str());
                         vite_str::format!("→ Cache miss: {desc}")
                     }
+                    SavedCacheMissReason::TrackedEnvChanged(mismatch) => {
+                        vite_str::format!("→ Cache miss: {mismatch}")
+                    }
                 },
             },
         }