feat(cache): honor runner ignored outputs

Co-authored-by: GPT-5 Codex <codex@openai.com>

Author: wan9chi

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 - **Added** Runner-aware tools can now call `ignoreInput(path)` to exclude non-semantic reads from auto-inferred task cache inputs.
+- **Added** Runner-aware tools can now call `ignoreOutput(path)` to exclude non-semantic writes from read/write overlap checks.
 - **Changed** Tracked environment values in task cache fingerprints are now stored only as SHA-256 digests, and env-related cache miss details report names without values.
 - **Added** Runner-aware `getEnvs` match sets can now participate in task cache fingerprints, so changing, adding, or removing a matching env var invalidates the cache ([#450](https://github.com/voidzero-dev/vite-task/pull/450)).
 - **Added** Runner-aware `getEnvs` calls now return env values served by the runner for matching env glob patterns ([#449](https://github.com/voidzero-dev/vite-task/pull/449)).

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

@@ -73,6 +73,9 @@ pub(super) async fn update_cache(
     let ignored_input_rels: FxHashSet<RelativePathBuf> = reports
         .map(|r| normalize_ignored_paths(&r.ignored_inputs, workspace_root))
         .unwrap_or_default();
+    let ignored_output_rels: FxHashSet<RelativePathBuf> = reports
+        .map(|r| normalize_ignored_paths(&r.ignored_outputs, workspace_root))
+        .unwrap_or_default();
 
     if cancelled {
         // Cancelled (Ctrl-C or sibling failure) — result is untrustworthy.
@@ -84,8 +87,13 @@ pub(super) async fn update_cache(
         return (CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::NonZeroExitStatus), None);
     }
 
-    let fspy_outcome =
-        observe_fspy(outcome, input_negative_globs, &ignored_input_rels, workspace_root);
+    let fspy_outcome = observe_fspy(
+        outcome,
+        input_negative_globs,
+        &ignored_input_rels,
+        &ignored_output_rels,
+        workspace_root,
+    );
 
     if let Some(TrackingOutcome { read_write_overlap: Some(path), .. }) = &fspy_outcome {
         // fspy-inferred read-write overlap: the task wrote to a file it also
@@ -176,6 +184,7 @@ fn observe_fspy(
     outcome: &ChildOutcome,
     input_negative_globs: Option<&[wax::Glob<'static>]>,
     ignored_input_rels: &FxHashSet<RelativePathBuf>,
+    ignored_output_rels: &FxHashSet<RelativePathBuf>,
     workspace_root: &AbsolutePath,
 ) -> Option<TrackingOutcome> {
     #[cfg(fspy)]
@@ -189,14 +198,22 @@ fn observe_fspy(
                 .into_iter()
                 .filter(|(path, _)| !is_ignored(path, ignored_input_rels))
                 .collect();
-            let read_write_overlap =
-                path_reads.keys().find(|p| tracked.path_writes.contains(*p)).cloned();
+            let read_write_overlap = path_reads
+                .keys()
+                .find(|p| tracked.path_writes.contains(*p) && !is_ignored(p, ignored_output_rels))
+                .cloned();
             TrackingOutcome { path_reads, read_write_overlap }
         })
     }
     #[cfg(not(fspy))]
     {
-        let _ = (outcome, input_negative_globs, ignored_input_rels, workspace_root);
+        let _ = (
+            outcome,
+            input_negative_globs,
+            ignored_input_rels,
+            ignored_output_rels,
+            workspace_root,
+        );
         None
     }
 }
@@ -216,14 +233,15 @@ fn collect_tracked_reports(
 }
 
 /// Normalize tool-reported absolute paths to workspace-relative. Paths outside
-/// the workspace are dropped — they can't contribute to inputs.
+/// the workspace are dropped — they can't contribute to inputs or outputs.
 fn normalize_ignored_paths(
     paths: &FxHashSet<Arc<AbsolutePath>>,
     workspace_root: &AbsolutePath,
 ) -> FxHashSet<RelativePathBuf> {
     // On Windows, `workspace_root` may carry a `\\?\` extended-path prefix
-    // while a tool's `current_dir()`-based ignoreInput path doesn't. Try an
-    // alternate stripped root too so current-dir paths and fspy paths can meet.
+    // while a tool's `current_dir()`-based ignoreInput/ignoreOutput path
+    // doesn't. Try an alternate stripped root too so current-dir paths and
+    // fspy paths can meet.
     #[cfg(windows)]
     let workspace_root_stripped: Option<vite_path::AbsolutePathBuf> =
         windows_strip_verbatim_prefix(workspace_root.as_path().as_os_str());

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

@@ -0,0 +1,11 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { ignoreOutput } from '@voidzero-dev/vite-task-client';
+
+mkdirSync('sidecar', { recursive: true });
+writeFileSync('sidecar/tmp.txt', 'initial\n');
+readFileSync('sidecar/tmp.txt', 'utf8');
+writeFileSync('sidecar/tmp.txt', 'final\n');
+ignoreOutput('sidecar');
+
+mkdirSync('dist', { recursive: true });
+writeFileSync('dist/out.txt', 'ok\n');

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

@@ -29,6 +29,35 @@ steps = [
   ], comment = "cache hit: cache_like/ was ignored via ignoreInput" },
 ]
 
+[[e2e]]
+name = "ignore_output_allows_read_write_overlap"
+comment = """
+Exercises `ignoreOutput`. The task reads and writes `sidecar/tmp.txt`; without the ignore the runner's read-write overlap check would refuse to cache the run.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "ignore-output",
+  ], comment = "first run populates the cache" },
+  { argv = [
+    "vtt",
+    "rm",
+    "dist/out.txt",
+  ], comment = "remove the real output so the cache-hit restore is observable" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-output",
+  ], comment = "cache hit: sidecar/ writes were ignored" },
+  { argv = [
+    "vtt",
+    "print-file",
+    "dist/out.txt",
+  ], comment = "restored from the explicit output archive" },
+]
+
 [[e2e]]
 name = "disable_cache_forces_reexecution"
 comment = """

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

@@ -0,0 +1,37 @@
+# ignore_output_allows_read_write_overlap
+
+Exercises `ignoreOutput`. The task reads and writes `sidecar/tmp.txt`; without the ignore the runner's read-write overlap check would refuse to cache the run.
+
+## `vt run ignore-output`
+
+first run populates the cache
+
+```
+$ node scripts/ignore_output.mjs
+```
+
+## `vtt rm dist/out.txt`
+
+remove the real output so the cache-hit restore is observable
+
+```
+```
+
+## `vt run ignore-output`
+
+cache hit: sidecar/ writes were ignored
+
+```
+$ node scripts/ignore_output.mjs ◉ cache hit, replaying
+
+---
+vt run: cache hit.
+```
+
+## `vtt print-file dist/out.txt`
+
+restored from the explicit output archive
+
+```
+ok
+```

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

@@ -4,6 +4,11 @@
       "command": "node scripts/ignore_input.mjs",
       "cache": true
     },
+    "ignore-output": {
+      "command": "node scripts/ignore_output.mjs",
+      "output": ["dist/**"],
+      "cache": true
+    },
     "disable-cache": {
       "command": "node scripts/disable_cache.mjs",
       "cache": true

crates/vite_task_client/src/lib.rs

@@ -65,6 +65,17 @@ impl Client {
         self.send(&Request::IgnoreInput(&ns))
     }
 
+    /// Fire-and-forget — see [`Self::ignore_input`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request fails to send, or if a relative `path`
+    /// cannot be resolved against the current working directory.
+    pub fn ignore_output(&self, path: &OsStr) -> io::Result<()> {
+        let ns = resolve_path(path)?;
+        self.send(&Request::IgnoreOutput(&ns))
+    }
+
     /// Fire-and-forget — see [`Self::ignore_input`].
     ///
     /// # Errors

crates/vite_task_client_napi/src/lib.rs

@@ -28,15 +28,6 @@
     clippy::needless_pass_by_value,
     reason = "napi bindings require owned std String + std::format! at the JS boundary"
 )]
-// The no-op methods must keep the exact signature of the real implementations
-// that replace them (instance method, fallible return), so the JS-visible API
-// shape never changes.
-#![expect(
-    clippy::unused_self,
-    clippy::unnecessary_wraps,
-    reason = "no-op stubs keep the signature of the real implementations that replace them"
-)]
-
 use std::{collections::HashMap, ffi::OsStr};
 
 use napi::{Error, Result};
@@ -62,11 +53,6 @@ pub struct GetEnvOptions {
 
 /// Handle returned by [`load`]. Holds the IPC connection and exposes the
 /// runner-side operations as instance methods.
-///
-/// The full client surface exists from the start because the npm-published
-/// JS wrapper calls these methods unconditionally — they must exist in
-/// every runner version. Verbs the runner cannot consume yet are no-ops
-/// here and become real requests in the follow-up that consumes them.
 #[napi]
 pub struct RunnerClient {
     client: Client,
@@ -81,10 +67,11 @@ impl RunnerClient {
             .map_err(|err| err_string(vite_str::format!("{err}")))
     }
 
-    /// No-op for now — see [`Self::ignore_input`].
     #[napi]
-    pub fn ignore_output(&self, _path: String) -> Result<()> {
-        Ok(())
+    pub fn ignore_output(&self, path: String) -> Result<()> {
+        self.client
+            .ignore_output(OsStr::new(&path))
+            .map_err(|err| err_string(vite_str::format!("{err}")))
     }
 
     #[napi]

crates/vite_task_ipc_shared/src/lib.rs

@@ -16,9 +16,10 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 
 /// IPC request frame sent by tools to the runner.
 ///
-/// `IgnoreInput` and `DisableCache` are fire-and-forget: the runner processes
-/// them when they arrive and never writes a response. `GetEnv` and `GetEnvs`
-/// are round-trips and pair with the matching response types below.
+/// `IgnoreInput`, `IgnoreOutput`, and `DisableCache` are fire-and-forget:
+/// the runner processes them when they arrive and never writes a response.
+/// `GetEnv` and `GetEnvs` are round-trips and pair with the matching response
+/// types below.
 ///
 /// Fire-and-forget is safe because nothing in the runner observes individual
 /// IPC events live — the recorded set is only consumed *after* the per-task
@@ -28,6 +29,7 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub enum Request<'a> {
     IgnoreInput(&'a NativeStr),
+    IgnoreOutput(&'a NativeStr),
     GetEnv { name: &'a NativeStr, tracked: bool },
     GetEnvs { pattern: &'a str, tracked: bool },
     DisableCache,

crates/vite_task_server/src/lib.rs

@@ -16,6 +16,7 @@ use wincode::{SchemaWrite, config::DefaultConfig};
 
 pub trait Handler {
     fn ignore_input(&mut self, path: &Arc<AbsolutePath>);
+    fn ignore_output(&mut self, path: &Arc<AbsolutePath>);
     fn disable_cache(&mut self);
     fn get_env(&mut self, name: &OsStr, tracked: bool) -> Option<Arc<OsStr>>;
     /// Returns the subset of the env map whose names match `pattern` as a glob.
@@ -66,6 +67,7 @@ pub struct InvalidGlob {
 /// recover the collected [`Reports`].
 pub struct Recorder {
     ignored_inputs: FxHashSet<Arc<AbsolutePath>>,
+    ignored_outputs: FxHashSet<Arc<AbsolutePath>>,
     cache_disabled: bool,
     tracked_get_env: FxHashMap<Arc<OsStr>, Option<Arc<OsStr>>>,
     tracked_get_envs: FxHashMap<Arc<str>, EnvGlobRecord>,
@@ -87,6 +89,7 @@ pub struct EnvGlobRecord {
 #[derive(Debug, Default)]
 pub struct Reports {
     pub ignored_inputs: FxHashSet<Arc<AbsolutePath>>,
+    pub ignored_outputs: FxHashSet<Arc<AbsolutePath>>,
     pub cache_disabled: bool,
     pub tracked_get_env: FxHashMap<Arc<OsStr>, Option<Arc<OsStr>>>,
     pub tracked_get_envs: FxHashMap<Arc<str>, EnvGlobRecord>,
@@ -97,6 +100,7 @@ impl Recorder {
     pub fn new(envs: Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>) -> Self {
         Self {
             ignored_inputs: FxHashSet::default(),
+            ignored_outputs: FxHashSet::default(),
             cache_disabled: false,
             tracked_get_env: FxHashMap::default(),
             tracked_get_envs: FxHashMap::default(),
@@ -108,6 +112,7 @@ impl Recorder {
     pub fn into_reports(self) -> Reports {
         Reports {
             ignored_inputs: self.ignored_inputs,
+            ignored_outputs: self.ignored_outputs,
             cache_disabled: self.cache_disabled,
             tracked_get_env: self.tracked_get_env,
             tracked_get_envs: self.tracked_get_envs,
@@ -120,6 +125,10 @@ impl Handler for Recorder {
         self.ignored_inputs.insert(Arc::clone(path));
     }
 
+    fn ignore_output(&mut self, path: &Arc<AbsolutePath>) {
+        self.ignored_outputs.insert(Arc::clone(path));
+    }
+
     fn disable_cache(&mut self) {
         self.cache_disabled = true;
     }
@@ -374,7 +383,7 @@ async fn handle_client<H: Handler>(mut stream: Stream, handler: &RefCell<H>) ->
         let request: Request<'_> =
             wincode::deserialize_exact(&buf).map_err(Error::InvalidRequest)?;
 
-        // Fire-and-forget branches (`IgnoreInput`, `DisableCache`)
+        // Fire-and-forget branches (`IgnoreInput`, `IgnoreOutput`, `DisableCache`)
         // intentionally write no response. Nothing in the runner observes
         // individual IPC events live; the recorded set is collected after
         // this driver drains. See `Request` in `vite_task_ipc_shared` for
@@ -384,6 +393,10 @@ async fn handle_client<H: Handler>(mut stream: Stream, handler: &RefCell<H>) ->
                 let path = native_str_to_abs_path(ns)?;
                 handler.borrow_mut().ignore_input(&path);
             }
+            Request::IgnoreOutput(ns) => {
+                let path = native_str_to_abs_path(ns)?;
+                handler.borrow_mut().ignore_output(&path);
+            }
             Request::DisableCache => {
                 handler.borrow_mut().disable_cache();
             }