feat(cache): runner-aware env tracking via getEnv/getEnvs

Makes the addon's getEnv/getEnvs no-ops real — protocol verbs, sync
client round-trips, and server-side serving — and fingerprints the
served values so changing them invalidates the cache:

- getEnv/getEnvs are served from the spawn's full env context saved in
  the plan: the same env map the task is spawned with, including
  command-prefix and nested-run prefix envs. std::env::vars_os is read
  exactly once to bootstrap the session env snapshot (enforced by
  clippy).
- Served values and glob match-sets are recorded in the post-run
  fingerprint and validated on the next lookup; prerun and postrun env
  mismatches share one EnvMismatch enum, and misses name the env var
  inline (cache miss: env 'NODE_ENV' changed).
- E2E: direct-client fixtures cover value changes, glob match-set
  changes, and prefix-env visibility; real vite build re-runs on
  NODE_ENV/prefix-env changes via the served values.

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

Author: wan9chi

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- **Added** Runner-aware env tracking: tools can ask the runner for env values via `getEnv`/`getEnvs`, and the served values (and glob match-sets) become part of the cache fingerprint, so changing them invalidates the cache with the env var named in the miss message ([#430](https://github.com/voidzero-dev/vite-task/pull/430))
 - **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))

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:

Cargo.lock

@@ -158,7 +158,6 @@ fn register_preload_cdylib() -> anyhow::Result<()> {
 }
 
 fn main() -> anyhow::Result<()> {
-    println!("cargo:rerun-if-changed=build.rs");
     let out_dir = PathBuf::from(env::var_os("OUT_DIR").unwrap());
     fetch_macos_binaries(&out_dir).context("Failed to fetch macOS binaries")?;
     register_preload_cdylib().context("Failed to register preload cdylib")?;

crates/fspy/build.rs

@@ -37,7 +37,7 @@ use wincode::{
 /// **Not portable across platforms.** The binary representation is platform-specific.
 /// Deserializing a `NativeStr` serialized on a different platform leads to unspecified
 /// behavior (garbage data), but is not unsafe. Designed for same-platform IPC only.
-#[derive(TransparentWrapper, PartialEq, Eq)]
+#[derive(TransparentWrapper, PartialEq, Eq, Hash)]
 #[repr(transparent)]
 pub struct NativeStr {
     // On unix, this is the raw bytes of the OsStr.

crates/native_str/src/lib.rs

@@ -45,6 +45,7 @@ tracing = { workspace = true }
 twox-hash = { workspace = true }
 materialized_artifact = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
+vite_glob = { workspace = true }
 vite_path = { workspace = true }
 vite_select = { workspace = true }
 vite_str = { workspace = true }

crates/vite_task/Cargo.toml

@@ -92,7 +92,7 @@ The cache entry key uniquely identifies a command execution context:
 ```rust
 pub struct CacheEntryKey {
     pub spawn_fingerprint: SpawnFingerprint,
-    pub input_config: ResolvedInputConfig,
+    pub input_config: ResolvedGlobConfig,
 }
 ```
 
@@ -303,7 +303,7 @@ Cache entries are serialized using `bincode` for efficient storage.
 │  ──────────────────────                                      │
 │    CacheEntryKey {                                           │
 │        spawn_fingerprint: SpawnFingerprint { ... },          │
-│        input_config: ResolvedInputConfig { ... },            │
+│        input_config: ResolvedGlobConfig { ... },            │
 │    }                                                         │
 │    ExecutionCacheKey::UserTask {                              │
 │        task_name: "build",                                   │

crates/vite_task/docs/task-cache.md

@@ -120,8 +120,8 @@ pub fn detect_spawn_fingerprint_changes(
 }
 
 /// Names of the env vars involved in a set of spawn-fingerprint changes, in the
-/// order detected. Only env changes are collected; untracked-env and non-env
-/// changes are skipped.
+/// order detected. Only the tracked-env kinds are collected; untracked-env and
+/// non-env changes are skipped.
 fn env_change_names(changes: &[SpawnFingerprintChange]) -> Vec<&Str> {
     changes
         .iter()
@@ -195,6 +195,13 @@ pub fn format_cache_status_inline(cache_status: &CacheStatus) -> Option<Str> {
                 FingerprintMismatch::InputChanged { kind, path } => {
                     format_input_change_str(*kind, path.as_str())
                 }
+                // Env changes reported by a runner-aware tool render the same as
+                // changes detected from a manual `env` config — both name the
+                // env var that changed.
+                FingerprintMismatch::TrackedEnvChanged(mismatch)
+                | FingerprintMismatch::TrackedEnvGlobChanged { mismatch, .. } => {
+                    format_env_changed_inline(&[mismatch.name()])
+                }
             };
             Some(vite_str::format!("○ cache miss: {reason}, executing"))
         }

crates/vite_task/src/session/cache/display.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};
@@ -142,9 +145,10 @@ pub enum InputChangeKind {
 /// A single env var difference between a stored fingerprint and the current
 /// environment.
 ///
-/// The canonical shape for an env change wherever one is detected and
-/// reported. The [`Display`] impl is the single source of the user-facing
-/// wording.
+/// Shared by the prerun (spawn fingerprint) and post-run (tool-tracked env /
+/// env glob) mismatch paths, so every env change is reported and rendered the
+/// same way regardless of where it was detected. The [`Display`] impl is the
+/// single source of the user-facing wording.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum EnvMismatch {
     /// Set now, but absent from the stored fingerprint.
@@ -165,6 +169,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,22 +219,24 @@ pub enum FingerprintMismatch {
         kind: InputChangeKind,
         path: RelativePathBuf,
     },
+    /// A tool-tracked env var changed between runs.
+    TrackedEnvChanged(EnvMismatch),
+    /// A tool-tracked env glob's match-set changed between runs. Carries the
+    /// first differing entry.
+    TrackedEnvGlobChanged {
+        pattern: Str,
+        mismatch: 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),
+            PostRunMismatch::TrackedEnvGlobChanged { pattern, mismatch } => {
+                Self::TrackedEnvGlobChanged { pattern, mismatch }
             }
         }
     }
@@ -240,7 +263,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
@@ -286,12 +309,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;
@@ -307,11 +334,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