feat(client): add tracked option for env IPC (#458)

## Motivation

Some tools need to ask the runner for env values without making those reads cache dependencies. The default should stay safe, but callers need an explicit opt-out for env reads that only affect diagnostics or optional behavior.

## Scope

Add a `tracked` flag to both `getEnv` and `getEnvs` IPC requests and Rust/Node clients. The option defaults to `true`; `tracked: false` still serves the env value or match set but filters that read out of the post-run cache fingerprint. IPC records keep the tracked flag monotonic so a later tracked read of the same name or pattern wins over an earlier untracked read.

This PR is intentionally placed after the getEnvs fingerprint PR so the opt-out is implemented against both env APIs at once.

## Verification

- `cargo check -p vite_task`
- `cargo test -p vite_task_server --test integration`
- `cargo test -p vite_task_bin --test e2e_snapshots fetch_env_untracked_does_not_invalidate -- --ignored`
- `cargo test -p vite_task_bin --test e2e_snapshots fetch_envs_untracked_does_not_invalidate -- --ignored`
- `cargo clippy --locked --all-targets --all-features -- -D warnings`

Author: wan9chi

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

@@ -211,7 +211,7 @@ fn collect_tracked_envs(
     let fingerprinted = &metadata.spawn_fingerprint.env_fingerprints().fingerprinted_envs;
     let mut tracked_envs = BTreeMap::new();
 
-    for (name, value) in &reports.env_records {
+    for (name, value) in &reports.tracked_get_env {
         let name_str =
             name.to_str().ok_or_else(|| anyhow::anyhow!("tracked env name is not valid UTF-8"))?;
         if fingerprinted.contains_key(name_str) {
@@ -237,7 +237,7 @@ fn collect_tracked_envs(
 fn collect_tracked_env_globs(reports: &Reports) -> anyhow::Result<TrackedEnvGlobValues> {
     let mut tracked_env_globs = BTreeMap::new();
 
-    for (pattern, record) in &reports.env_glob_records {
+    for (pattern, record) in &reports.tracked_get_envs {
         let mut matches = BTreeMap::new();
         for (name, value) in &record.matches {
             let name_str = name

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

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

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

@@ -1,6 +1,7 @@
 import { getEnvs } from '@voidzero-dev/vite-task-client';
 
-const matches = getEnvs('PROBE_*');
+const tracked = process.argv[2] === '--untracked' ? false : true;
+const matches = getEnvs('PROBE_*', { tracked });
 const sorted = Object.entries(matches).sort(([a], [b]) => a.localeCompare(b));
 
 for (const [key, value] of sorted) {

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

@@ -299,3 +299,73 @@ steps = [
     ],
   ], comment = "non-matching noise: UNRELATED does not match PROBE_* -> cache hit" },
 ]
+
+[[e2e]]
+name = "fetch_env_untracked_does_not_invalidate"
+comment = """
+Exercises `getEnv(name, { tracked: false })`. The runner still serves the env value, but the value does not enter the post-run fingerprint, so changing it later replays the cached output.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-env-untracked",
+  ], envs = [
+    [
+      "PROBE_ENV",
+      "first",
+    ],
+  ], comment = "first run serves PROBE_ENV without tracking it" },
+  { argv = [
+    "vt",
+    "run",
+    "fetch-env-untracked",
+  ], envs = [
+    [
+      "PROBE_ENV",
+      "second",
+    ],
+  ], comment = "cache hit: PROBE_ENV changed but was requested with tracked: false" },
+]
+
+[[e2e]]
+name = "fetch_envs_untracked_does_not_invalidate"
+comment = """
+Exercises `getEnvs(pattern, { tracked: false })`. The runner still serves the matching envs, but the match set does not enter the post-run fingerprint, so changing it later replays the cached output.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-envs-untracked",
+  ], envs = [
+    [
+      "PROBE_A",
+      "a",
+    ],
+    [
+      "PROBE_B",
+      "b",
+    ],
+  ], comment = "first run serves the PROBE_* match set without tracking it" },
+  { argv = [
+    "vt",
+    "run",
+    "fetch-envs-untracked",
+  ], envs = [
+    [
+      "PROBE_A",
+      "changed",
+    ],
+    [
+      "PROBE_B",
+      "b",
+    ],
+    [
+      "PROBE_C",
+      "c",
+    ],
+  ], comment = "cache hit: changed match set was requested with tracked: false" },
+]

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

@@ -0,0 +1,26 @@
+# fetch_env_untracked_does_not_invalidate
+
+Exercises `getEnv(name, { tracked: false })`. The runner still serves the env value, but the value does not enter the post-run fingerprint, so changing it later replays the cached output.
+
+## `PROBE_ENV=first vt run fetch-env-untracked`
+
+first run serves PROBE_ENV without tracking it
+
+```
+$ node scripts/fetch_env.mjs --untracked PROBE_ENV
+served PROBE_ENV=first
+process.env PROBE_ENV=(unset)
+```
+
+## `PROBE_ENV=second vt run fetch-env-untracked`
+
+cache hit: PROBE_ENV changed but was requested with tracked: false
+
+```
+$ node scripts/fetch_env.mjs --untracked PROBE_ENV ◉ cache hit, replaying
+served PROBE_ENV=first
+process.env PROBE_ENV=(unset)
+
+---
+vt run: cache hit.
+```

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

@@ -0,0 +1,26 @@
+# fetch_envs_untracked_does_not_invalidate
+
+Exercises `getEnvs(pattern, { tracked: false })`. The runner still serves the matching envs, but the match set does not enter the post-run fingerprint, so changing it later replays the cached output.
+
+## `PROBE_A=a PROBE_B=b vt run fetch-envs-untracked`
+
+first run serves the PROBE_* match set without tracking it
+
+```
+$ node scripts/fetch_envs.mjs --untracked
+PROBE_A=a
+PROBE_B=b
+```
+
+## `PROBE_A=changed PROBE_B=b PROBE_C=c vt run fetch-envs-untracked`
+
+cache hit: changed match set was requested with tracked: false
+
+```
+$ node scripts/fetch_envs.mjs --untracked ◉ cache hit, replaying
+PROBE_A=a
+PROBE_B=b
+
+---
+vt run: cache hit.
+```

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

@@ -24,6 +24,14 @@
       "command": "node scripts/fetch_envs.mjs",
       "cache": true
     },
+    "fetch-env-untracked": {
+      "command": "node scripts/fetch_env.mjs --untracked PROBE_ENV",
+      "cache": true
+    },
+    "fetch-envs-untracked": {
+      "command": "node scripts/fetch_envs.mjs --untracked",
+      "cache": true
+    },
     "fetch-prefixed-env": {
       "command": "PREFIXED_ENV=from-command node scripts/fetch_env.mjs PREFIXED_ENV",
       "cache": true

crates/vite_task_client/src/lib.rs

@@ -64,10 +64,10 @@ impl Client {
     /// # Errors
     ///
     /// Returns an error if the request or response fails.
-    pub fn get_env(&self, name: &OsStr) -> io::Result<Option<Arc<OsStr>>> {
+    pub fn get_env(&self, name: &OsStr, tracked: bool) -> io::Result<Option<Arc<OsStr>>> {
         let name = Box::<NativeStr>::from(name);
 
-        self.send(&Request::GetEnv { name: &name })?;
+        self.send(&Request::GetEnv { name: &name, tracked })?;
         let response: GetEnvResponse = self.recv()?;
         Ok(response
             .env_value
@@ -81,8 +81,12 @@ impl Client {
     ///
     /// Returns an error if the request or response fails, or if the server
     /// rejects the pattern as an invalid glob.
-    pub fn get_envs(&self, pattern: &str) -> io::Result<FxHashMap<Arc<OsStr>, Arc<OsStr>>> {
-        self.send(&Request::GetEnvs { pattern })?;
+    pub fn get_envs(
+        &self,
+        pattern: &str,
+        tracked: bool,
+    ) -> io::Result<FxHashMap<Arc<OsStr>, Arc<OsStr>>> {
+        self.send(&Request::GetEnvs { pattern, tracked })?;
         let response: GetEnvsResponse = self.recv()?;
         Ok(response
             .entries

crates/vite_task_client_napi/src/lib.rs

@@ -93,10 +93,11 @@ impl RunnerClient {
     }
 
     #[napi]
-    pub fn get_env(&self, name: String, _options: Option<GetEnvOptions>) -> Result<Option<String>> {
+    pub fn get_env(&self, name: String, options: Option<GetEnvOptions>) -> Result<Option<String>> {
+        let tracked = options.and_then(|o| o.tracked).unwrap_or(true);
         let value = self
             .client
-            .get_env(OsStr::new(&name))
+            .get_env(OsStr::new(&name), tracked)
             .map_err(|err| err_string(vite_str::format!("{err}")))?;
         value.map_or(Ok(None), |value| {
             value.to_str().map(|s| Some(s.to_owned())).ok_or_else(|| {
@@ -109,10 +110,13 @@ impl RunnerClient {
     pub fn get_envs(
         &self,
         pattern: String,
-        _options: Option<GetEnvOptions>,
+        options: Option<GetEnvOptions>,
     ) -> Result<HashMap<String, String>> {
-        let matches =
-            self.client.get_envs(&pattern).map_err(|err| err_string(vite_str::format!("{err}")))?;
+        let tracked = options.and_then(|o| o.tracked).unwrap_or(true);
+        let matches = self
+            .client
+            .get_envs(&pattern, tracked)
+            .map_err(|err| err_string(vite_str::format!("{err}")))?;
         let mut result = HashMap::with_capacity(matches.len());
         for (name, value) in matches {
             let name = name.to_str().ok_or_else(|| {

crates/vite_task_ipc_shared/src/lib.rs

@@ -27,8 +27,8 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 /// will still consume every buffered frame.
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub enum Request<'a> {
-    GetEnv { name: &'a NativeStr },
-    GetEnvs { pattern: &'a str },
+    GetEnv { name: &'a NativeStr, tracked: bool },
+    GetEnvs { pattern: &'a str, tracked: bool },
     DisableCache,
 }