feat(cache): add explicit auto output tracking

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

Author: wan9chi

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - **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.
+- **Added** Cached tasks can opt into automatic output restoration with `output: [{ auto: true }]`.
 - **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

@@ -28,6 +28,9 @@ use crate::{
 /// value is only ever `Some` when tracking happened (see [`observe_fspy`]).
 struct TrackingOutcome {
     path_reads: HashMap<RelativePathBuf, PathRead>,
+    /// All paths the task wrote to. Consumed by `collect_and_archive_outputs`
+    /// when `output_config.includes_auto` is set.
+    path_writes: FxHashSet<RelativePathBuf>,
     /// First path that was both read and written during execution, if any.
     /// A non-empty value means caching this task is unsound.
     read_write_overlap: Option<RelativePathBuf>,
@@ -89,6 +92,7 @@ pub(super) async fn update_cache(
 
     let fspy_outcome = observe_fspy(
         outcome,
+        metadata,
         input_negative_globs,
         &ignored_input_rels,
         &ignored_output_rels,
@@ -150,7 +154,13 @@ pub(super) async fn update_cache(
         }
     };
 
-    let output_archive = match collect_and_archive_outputs(metadata, workspace_root, cache_dir) {
+    let output_archive = match collect_and_archive_outputs(
+        metadata,
+        fspy_outcome.as_ref(),
+        &ignored_output_rels,
+        workspace_root,
+        cache_dir,
+    ) {
         Ok(archive) => archive,
         Err(err) => {
             return (
@@ -177,38 +187,58 @@ pub(super) async fn update_cache(
 }
 
 /// Summarize the run's fspy observations. `Some` iff tracking was both
-/// requested (`input_negative_globs.is_some()`) and compiled in (`cfg(fspy)`). On a
+/// requested (`tracking.fspy.is_some()`) and compiled in (`cfg(fspy)`). On a
 /// `cfg(not(fspy))` build this is always `None`, and [`update_cache`]
 /// short-circuits to `FspyUnsupported` when tracking was needed.
+///
+/// `path_reads` is gated on `input_config.includes_auto`, filtered by
+/// user-configured input negatives, and by tool-reported `ignoreInput` paths.
+/// `path_writes` is NOT filtered here — output negatives and `ignoreOutput`
+/// are applied later inside `collect_and_archive_outputs`.
 fn observe_fspy(
     outcome: &ChildOutcome,
+    metadata: &CacheMetadata,
     input_negative_globs: Option<&[wax::Glob<'static>]>,
     ignored_input_rels: &FxHashSet<RelativePathBuf>,
     ignored_output_rels: &FxHashSet<RelativePathBuf>,
     workspace_root: &AbsolutePath,
 ) -> Option<TrackingOutcome> {
     #[cfg(fspy)]
     {
+        use wax::Program as _;
+
         use super::tracked_accesses::TrackedPathAccesses;
 
-        outcome.path_accesses.as_ref().zip(input_negative_globs).map(|(raw, negatives)| {
-            let tracked = TrackedPathAccesses::from_raw(raw, workspace_root, negatives);
-            let path_reads: HashMap<RelativePathBuf, PathRead> = tracked
-                .path_reads
-                .into_iter()
-                .filter(|(path, _)| !is_ignored(path, ignored_input_rels))
-                .collect();
+        outcome.path_accesses.as_ref().map(|raw| {
+            let tracked = TrackedPathAccesses::from_raw(raw, workspace_root);
+            let path_reads: HashMap<RelativePathBuf, PathRead> =
+                if metadata.input_config.includes_auto
+                    && let Some(negatives) = input_negative_globs
+                {
+                    tracked
+                        .path_reads
+                        .iter()
+                        .filter(|(path, _)| {
+                            !negatives.iter().any(|neg| neg.is_match(path.as_str()))
+                                && !is_ignored(path, ignored_input_rels)
+                        })
+                        .map(|(path, read)| (path.clone(), *read))
+                        .collect()
+                } else {
+                    HashMap::default()
+                };
             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 }
+            TrackingOutcome { path_reads, path_writes: tracked.path_writes, read_write_overlap }
         })
     }
     #[cfg(not(fspy))]
     {
         let _ = (
             outcome,
+            metadata,
             input_negative_globs,
             ignored_input_rels,
             ignored_output_rels,
@@ -307,36 +337,64 @@ fn collect_tracked_env_globs(reports: &Reports) -> anyhow::Result<TrackedEnvGlob
     Ok(tracked_env_globs)
 }
 
-/// Collect output files matching the configured globs and create a tar.zst
-/// archive in the cache directory.
+/// Collect output files and create a tar.zst archive in the cache directory.
+///
+/// Output files are determined by:
+/// - fspy-tracked writes (when `output_config.includes_auto` is true)
+/// - Positive output globs (always, if configured)
+/// - Filtered by negative output globs
+/// - Filtered by tool-reported `ignoreOutput` paths (auto writes only)
 ///
-/// Returns `Some(archive_filename)` if files were archived, `None` if the
-/// output config has no positive globs or no files matched.
+/// Returns `Some(archive_filename)` if files were archived, `None` if no output files.
 fn collect_and_archive_outputs(
     cache_metadata: &CacheMetadata,
+    tracking: Option<&TrackingOutcome>,
+    ignored_output_rels: &FxHashSet<RelativePathBuf>,
     workspace_root: &AbsolutePath,
     cache_dir: &AbsolutePath,
 ) -> anyhow::Result<Option<Str>> {
+    use wax::Program as _;
+
     let output_config = &cache_metadata.output_config;
 
-    if output_config.positive_globs.is_empty() {
-        return Ok(None);
+    let mut output_files: FxHashSet<RelativePathBuf> = FxHashSet::default();
+
+    if output_config.includes_auto
+        && let Some(t) = tracking
+    {
+        output_files
+            .extend(t.path_writes.iter().filter(|p| !is_ignored(p, ignored_output_rels)).cloned());
     }
 
-    let output_files = glob::collect_glob_paths(
-        workspace_root,
-        &output_config.positive_globs,
-        &output_config.negative_globs,
-    )?;
+    if !output_config.positive_globs.is_empty() {
+        let glob_paths = glob::collect_glob_paths(
+            workspace_root,
+            &output_config.positive_globs,
+            &output_config.negative_globs,
+        )?;
+        output_files.extend(glob_paths);
+    }
+
+    if output_config.includes_auto && !output_config.negative_globs.is_empty() {
+        let negatives: Vec<wax::Glob<'static>> = output_config
+            .negative_globs
+            .iter()
+            .map(|p| Ok(wax::Glob::new(p.as_str())?.into_owned()))
+            .collect::<anyhow::Result<_>>()?;
+        output_files.retain(|path| !negatives.iter().any(|neg| neg.is_match(path.as_str())));
+    }
 
     if output_files.is_empty() {
         return Ok(None);
     }
 
+    let mut sorted_files: Vec<RelativePathBuf> = output_files.into_iter().collect();
+    sorted_files.sort();
+
     let archive_name: Str = vite_str::format!("{}.tar.zst", uuid::Uuid::new_v4());
     let archive_path = cache_dir.join(archive_name.as_str());
 
-    archive::create_output_archive(workspace_root, &output_files, &archive_path)?;
+    archive::create_output_archive(workspace_root, &sorted_files, &archive_path)?;
 
     Ok(Some(archive_name))
 }

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

@@ -89,9 +89,9 @@ struct CacheState<'a> {
     /// always present (possibly empty) once we reach the cache-update phase.
     std_outputs: Vec<StdOutput>,
     /// Runner-aware tracking for cached tasks: an IPC server is always
-    /// available, and fspy path tracing is attached only when auto input
-    /// inference needs it. Parts are borrowed in place during the wait/join;
-    /// the struct is never moved out.
+    /// available, and fspy path tracing is attached only when auto input or
+    /// output inference needs it. Parts are borrowed in place during the
+    /// wait/join; the struct is never moved out.
     tracking: Tracking,
 }
 
@@ -100,7 +100,7 @@ struct CacheState<'a> {
 type IpcDriver = LocalBoxFuture<'static, Result<Recorder, vite_task_server::Error>>;
 
 /// fspy path-tracking state, present only when a cached task needs automatic
-/// input inference.
+/// input or output inference.
 struct FspyTracking {
     input_negative_globs: Vec<wax::Glob<'static>>,
 }
@@ -164,7 +164,7 @@ impl<'a> ExecutionMode<'a> {
             });
         };
 
-        let fspy = if metadata.input_config.includes_auto {
+        let fspy = if metadata.input_config.includes_auto || metadata.output_config.includes_auto {
             // Resolve input negative globs for fspy path filtering (already
             // workspace-root-relative).
             let negatives = metadata

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

@@ -1,4 +1,8 @@
 //! Normalize raw fspy path accesses into workspace-relative, filtered form.
+//!
+//! User-configured negative globs are NOT applied here. They are applied later,
+//! separately for reads (input config) and writes (output config), since those
+//! two configs are independent.
 #![cfg(fspy)]
 
 use std::collections::hash_map::Entry;
@@ -21,22 +25,19 @@ pub struct TrackedPathAccesses {
 }
 
 impl TrackedPathAccesses {
-    /// Build from fspy's raw iterable by stripping the workspace prefix,
-    /// normalizing `..` components, and filtering against the negative globs.
-    pub fn from_raw(
-        raw: &PathAccessIterable,
-        workspace_root: &AbsolutePath,
-        resolved_negatives: &[wax::Glob<'static>],
-    ) -> Self {
+    /// Build from fspy's raw iterable by stripping the workspace prefix and
+    /// normalizing `..` components. `.git/*` paths are skipped. User-configured
+    /// negatives are applied by the caller (see module docs).
+    pub fn from_raw(raw: &PathAccessIterable, workspace_root: &AbsolutePath) -> Self {
         let mut accesses = Self::default();
         for access in raw.iter() {
-            // Strip workspace root, clean `..` components, and filter in one pass.
+            // Strip workspace root and clean `..` components in one pass.
             // fspy may report paths like `packages/sub-pkg/../shared/dist/output.js`.
             let relative_path = access.path.strip_path_prefix(workspace_root, |strip_result| {
                 let Ok(stripped_path) = strip_result else {
                     return None;
                 };
-                normalize_tracked_workspace_path(stripped_path, resolved_negatives)
+                normalize_tracked_workspace_path(stripped_path)
             });
 
             let Some(relative_path) = relative_path else {
@@ -71,10 +72,7 @@ impl TrackedPathAccesses {
     clippy::disallowed_types,
     reason = "fspy strip_path_prefix exposes std::path::Path; convert to RelativePathBuf immediately"
 )]
-fn normalize_tracked_workspace_path(
-    stripped_path: &std::path::Path,
-    resolved_negatives: &[wax::Glob<'static>],
-) -> Option<RelativePathBuf> {
+fn normalize_tracked_workspace_path(stripped_path: &std::path::Path) -> Option<RelativePathBuf> {
     // On Windows, paths are possible to be still absolute after stripping the workspace root.
     // For example: c:\workspace\subdir\c:\workspace\subdir
     // Just ignore those accesses.
@@ -90,12 +88,6 @@ fn normalize_tracked_workspace_path(
         return None;
     }
 
-    if !resolved_negatives.is_empty()
-        && resolved_negatives.iter().any(|neg| wax::Program::is_match(neg, relative.as_str()))
-    {
-        return None;
-    }
-
     Some(relative)
 }
 
@@ -111,8 +103,7 @@ mod tests {
             clippy::disallowed_types,
             reason = "normalize_tracked_workspace_path requires std::path::Path for fspy strip_path_prefix output"
         )]
-        let relative_path =
-            normalize_tracked_workspace_path(std::path::Path::new(r"foo\C:\bar"), &[]);
+        let relative_path = normalize_tracked_workspace_path(std::path::Path::new(r"foo\C:\bar"));
         assert!(relative_path.is_none());
     }
 }

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

@@ -58,6 +58,35 @@ steps = [
   ], comment = "restored from the explicit output archive" },
 ]
 
+[[e2e]]
+name = "explicit_auto_output_restores_written_files"
+comment = """
+Exercises `output: [{ auto: true }]` with explicit inputs disabled. The runner attaches fspy for output tracking, archives the written file, and restores it on cache hit.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "auto-output-explicit",
+  ], comment = "first run writes dist/auto.txt and archives fspy-tracked outputs" },
+  { argv = [
+    "vtt",
+    "rm",
+    "dist/auto.txt",
+  ], comment = "remove the output so restoration is observable" },
+  { argv = [
+    "vt",
+    "run",
+    "auto-output-explicit",
+  ], comment = "cache hit: fspy-tracked output is restored" },
+  { argv = [
+    "vtt",
+    "print-file",
+    "dist/auto.txt",
+  ], comment = "restored from the auto output archive" },
+]
+
 [[e2e]]
 name = "disable_cache_forces_reexecution"
 comment = """

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

@@ -0,0 +1,37 @@
+# explicit_auto_output_restores_written_files
+
+Exercises `output: [{ auto: true }]` with explicit inputs disabled. The runner attaches fspy for output tracking, archives the written file, and restores it on cache hit.
+
+## `vt run auto-output-explicit`
+
+first run writes dist/auto.txt and archives fspy-tracked outputs
+
+```
+$ vtt write-file dist/auto.txt ok
+```
+
+## `vtt rm dist/auto.txt`
+
+remove the output so restoration is observable
+
+```
+```
+
+## `vt run auto-output-explicit`
+
+cache hit: fspy-tracked output is restored
+
+```
+$ vtt write-file dist/auto.txt ok ◉ cache hit, replaying
+
+---
+vt run: cache hit.
+```
+
+## `vtt print-file dist/auto.txt`
+
+restored from the auto output archive
+
+```
+ok
+```

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

@@ -9,6 +9,12 @@
       "output": ["dist/**"],
       "cache": true
     },
+    "auto-output-explicit": {
+      "command": "vtt write-file dist/auto.txt ok",
+      "input": [],
+      "output": [{ "auto": true }],
+      "cache": true
+    },
     "disable-cache": {
       "command": "node scripts/disable_cache.mjs",
       "cache": true

crates/vite_task_graph/run-config.ts

@@ -62,9 +62,10 @@ input?: Array<string | GlobWithBase | AutoInput>,
  * - Omitted or `[]` (empty): no output archiving (default)
  * - Glob patterns (e.g. `"dist/**"`) select specific output files, relative to the package directory
  * - `{pattern: "...", base: "workspace" | "package"}` specifies a glob with an explicit base directory
+ * - `{auto: true}` enables automatic output tracking
  * - Negative patterns (e.g. `"!dist/cache/**"`) exclude matched files
  */
-output?: Array<string | GlobWithBase>, } | { 
+output?: Array<string | GlobWithBase | AutoInput>, } | { 
 /**
  * Whether to cache the task
  */