feat(cache): integrate runner-aware IPC reports

Replaces the previous PR's placeholder with the real
`vite_task_server::serve(...)` call: per-task IPC server, napi
addon embedded into the runner binary and materialized to disk on
first use, `VP_RUN_NODE_CLIENT_PATH` injected into the child so the
JS wrapper can `require()` it.

Cache integration: `Reports` collected from the IPC drive
`PostRunFingerprint` and the cache-update path —

- `ignore_input` reads → excluded from input fingerprint
- `ignore_output` writes → excluded from output archive
- `tracked_envs` (single name) + `tracked_env_globs` → folded into
  the post-run fingerprint so a value change misses the cache
- `disable_cache` → skips the cache-update path entirely
  (`ToolRequested`)
- IPC server bind/runtime failure → `IpcServerError` cache disable

End-to-end coverage via the `ipc_client_test` fixture set: one
fixture per API method, each exercising the real Rust ↔ JS path and
asserting the right cache behaviour. Adds `vtt` (test-only)
helpers `grep_file` and `stat_file` that the fixtures need.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wan9chi

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

@@ -43,18 +43,28 @@ tokio = { workspace = true, features = [
 tokio-util = { workspace = true }
 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 }
 vite_task_graph = { workspace = true }
+vite_task_ipc_shared = { workspace = true }
 vite_task_plan = { workspace = true }
 vite_task_server = { workspace = true }
 vite_workspace = { workspace = true }
 wax = { workspace = true }
 zstd = { workspace = true }
 
+# Artifact build-deps must be unconditional: cargo's resolver panics when
+# `artifact = "cdylib"` deps live under a `[target.cfg.build-dependencies]`
+# block on cross-compile.
+[build-dependencies]
+anyhow = { workspace = true }
+materialized_artifact_build = { workspace = true }
+vite_task_client_napi = { workspace = true }
+
 [dev-dependencies]
 tempfile = { workspace = true }
 

crates/vite_task/Cargo.toml

@@ -1,3 +1,13 @@
+#![expect(
+    clippy::disallowed_types,
+    clippy::disallowed_macros,
+    reason = "build.rs interfaces with std::path and cargo's env-var API"
+)]
+
+use std::{env, path::Path};
+
+use anyhow::Context;
+
 // Why `cfg(fspy)` instead of matching on `target_os` directly at each use site:
 // "fspy is available" is a single semantic predicate, but the underlying reason
 // (the `fspy` crate builds on windows/macos/linux) is a three-OS list that
@@ -7,12 +17,18 @@
 // over OSes. The OS allowlist lives in two spots that must stay in sync: this
 // file (for the rustc cfg) and the target-scoped dep block in Cargo.toml
 // (which Cargo resolves before build.rs runs, so it can't reuse this cfg).
-fn main() {
+fn main() -> anyhow::Result<()> {
     println!("cargo::rustc-check-cfg=cfg(fspy)");
     println!("cargo::rerun-if-changed=build.rs");
 
-    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap();
+    let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap();
     if matches!(target_os.as_str(), "windows" | "macos" | "linux") {
         println!("cargo::rustc-cfg=fspy");
     }
+
+    let env_name = "CARGO_CDYLIB_FILE_VITE_TASK_CLIENT_NAPI";
+    println!("cargo:rerun-if-env-changed={env_name}");
+    let dylib_path = env::var_os(env_name).with_context(|| format!("{env_name} not set"))?;
+    materialized_artifact_build::register("vite_task_client_napi", Path::new(&dylib_path));
+    Ok(())
 }

crates/vite_task/build.rs

@@ -1,5 +1,6 @@
 mod cli;
 mod collections;
+mod napi_client;
 pub mod session;
 
 // Public exports for vite_task_bin

crates/vite_task/src/lib.rs

@@ -0,0 +1,32 @@
+//! The `vite_task_client_napi` cdylib is embedded into the `vp` binary and
+//! materialized to disk on first use so tools can `require()` it at runtime.
+
+use std::{env, fs, sync::LazyLock};
+
+use materialized_artifact::artifact;
+use vite_path::{AbsolutePath, AbsolutePathBuf};
+
+/// Path to the materialized `vite_task_client_napi` `.node` addon.
+///
+/// The file is written to a process-wide temp directory on first call and
+/// reused on every subsequent call (content-addressed filename; no re-writes).
+///
+/// # Panics
+///
+/// Panics if the materialization fails on first call — this mirrors fspy's
+/// `SPY_IMPL` and the same reasoning applies: if we can't write into the
+/// system temp dir, the runner can't run tasks anyway.
+#[must_use]
+pub fn napi_client_path() -> &'static AbsolutePath {
+    static PATH: LazyLock<AbsolutePathBuf> = LazyLock::new(|| {
+        let dir = env::temp_dir().join("vite_task_client_napi");
+        let _ = fs::create_dir(&dir);
+        let path = artifact!("vite_task_client_napi")
+            .materialize()
+            .suffix(".node")
+            .at(&dir)
+            .expect("materialize vite_task_client_napi");
+        AbsolutePathBuf::new(path).expect("system temp dir yields an absolute path")
+    });
+    PATH.as_absolute_path()
+}

crates/vite_task/src/napi_client.rs

@@ -48,7 +48,6 @@ pub enum ExecutionError {
     /// The runner-aware IPC server failed to bind for this task. Reported
     /// instead of silently degrading so that `{ auto: true }` inputs stay
     /// observable end-to-end.
-    #[expect(dead_code, reason = "placeholder; constructed once the real `serve()` lands")]
     #[error("Failed to start runner IPC server")]
     IpcServerBind(#[source] std::io::Error),
 }

crates/vite_task/src/session/event.rs

@@ -24,11 +24,12 @@ use tokio::sync::Semaphore;
 use tokio_util::sync::CancellationToken;
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_str::Str;
+use vite_task_ipc_shared::NODE_CLIENT_PATH_ENV_NAME;
 use vite_task_plan::{
     ExecutionGraph, ExecutionItemDisplay, ExecutionItemKind, LeafExecutionKind, SpawnExecution,
     cache_metadata::CacheMetadata, execution_graph::ExecutionNodeIndex,
 };
-use vite_task_server::{Recorder, Reports, StopAccepting};
+use vite_task_server::{Recorder, Reports, ServerHandle, StopAccepting, serve};
 use wax::Program as _;
 
 #[cfg(fspy)]
@@ -499,25 +500,35 @@ pub async fn execute_spawn(
                             return SpawnOutcome::Failed;
                         }
                     };
-                    // PLACEHOLDER: the IPC server isn't wired up yet on this
-                    // branch. We construct an empty `Recorder` whose `Reports`
-                    // never get any IPC traffic, and a `StopAccepting::noop`
-                    // since no real server was bound. A follow-up will swap
-                    // these out for `vite_task_server::serve(...)`.
+                    // fspy + IPC are bundled. If binding the IPC server fails
+                    // we abort the execution — tools that rely on IPC would
+                    // otherwise silently diverge from the cache.
+                    //
+                    // The IPC `getEnv` endpoint serves values from the runner's
+                    // own parent env (not the task's filtered `all_envs`), so a
+                    // tool can ask for vars the user never declared and have
+                    // them fingerprinted via the tool's `tracked: true` flag.
                     let env_map: FxHashMap<Arc<OsStr>, Arc<OsStr>> = std::env::vars_os()
                         .map(|(k, v)| {
                             (Arc::<OsStr>::from(k.as_os_str()), Arc::<OsStr>::from(v.as_os_str()))
                         })
                         .collect();
-                    let recorder = Recorder::new(env_map);
-                    let driver: LocalBoxFuture<'static, Result<Recorder, vite_task_server::Error>> =
-                        Box::pin(std::future::ready(Ok(recorder)));
-                    Some(Tracking {
-                        input_negative_globs: negatives,
-                        ipc_envs: Vec::new(),
-                        ipc_server_fut: driver,
-                        stop_accepting: StopAccepting::noop(),
-                    })
+                    match serve(Recorder::new(env_map)) {
+                        Ok((envs, ServerHandle { driver, stop_accepting })) => Some(Tracking {
+                            input_negative_globs: negatives,
+                            ipc_envs: envs.collect(),
+                            ipc_server_fut: driver,
+                            stop_accepting,
+                        }),
+                        Err(err) => {
+                            leaf_reporter.finish(
+                                None,
+                                CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::CacheDisabled),
+                                Some(ExecutionError::IpcServerBind(err)),
+                            );
+                            return SpawnOutcome::Failed;
+                        }
+                    }
                 } else {
                     None
                 };
@@ -539,12 +550,17 @@ pub async fn execute_spawn(
         ExecutionMode::Uncached { pipe_writers: None } => (SpawnStdio::Inherited, false),
     };
 
-    // Build the extra envs to inject: IPC connection info + (eventually)
-    // napi addon path. Empty when tracking is off. The napi path is added
-    // in a follow-up that wires up the real server.
+    // Build the extra envs to inject: IPC connection info + napi addon path.
+    // Empty when tracking is off.
     let extra_envs: Vec<(&OsStr, &OsStr)> = match &mode {
         ExecutionMode::Cached { state: CacheState { tracking: Some(t), .. }, .. } => {
-            t.ipc_envs.iter().map(|(k, v)| (*k as &OsStr, v.as_os_str())).collect()
+            let mut envs: Vec<(&OsStr, &OsStr)> =
+                t.ipc_envs.iter().map(|(k, v)| (*k as &OsStr, v.as_os_str())).collect();
+            envs.push((
+                OsStr::new(NODE_CLIENT_PATH_ENV_NAME),
+                crate::napi_client::napi_client_path().as_path().as_os_str(),
+            ));
+            envs
         }
         _ => Vec::new(),
     };

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

@@ -0,0 +1,16 @@
+pub fn run(args: &[String]) {
+    let [path, pattern] = args else {
+        eprintln!("Usage: vtt grep-file <path> <pattern>");
+        std::process::exit(2);
+    };
+    match std::fs::read_to_string(path) {
+        Ok(content) => {
+            if content.contains(pattern.as_str()) {
+                println!("{path}: found {pattern:?}");
+            } else {
+                println!("{path}: missing {pattern:?}");
+            }
+        }
+        Err(_) => println!("{path}: not found"),
+    }
+}

crates/vite_task_bin/src/vtt/grep_file.rs

@@ -11,6 +11,7 @@ mod check_tty;
 mod cp;
 mod exit;
 mod exit_on_ctrlc;
+mod grep_file;
 mod list_dir;
 mod mkdir;
 mod pipe_stdin;
@@ -22,6 +23,7 @@ mod print_file;
 mod read_stdin;
 mod replace_file_content;
 mod rm;
+mod stat_file;
 mod touch_file;
 mod write_file;
 
@@ -30,7 +32,7 @@ fn main() {
     if args.len() < 2 {
         eprintln!("Usage: vtt <subcommand> [args...]");
         eprintln!(
-            "Subcommands: barrier, check-tty, cp, exit, exit-on-ctrlc, list-dir, mkdir, pipe-stdin, print, print-color, print-cwd, print-env, print-file, read-stdin, replace-file-content, rm, touch-file, write-file"
+            "Subcommands: barrier, check-tty, cp, exit, exit-on-ctrlc, grep-file, list-dir, mkdir, pipe-stdin, print, print-color, print-cwd, print-env, print-file, read-stdin, replace-file-content, rm, stat-file, touch-file, write-file"
         );
         std::process::exit(1);
     }
@@ -44,6 +46,10 @@ fn main() {
         "cp" => cp::run(&args[2..]),
         "exit" => exit::run(&args[2..]),
         "exit-on-ctrlc" => exit_on_ctrlc::run(),
+        "grep-file" => {
+            grep_file::run(&args[2..]);
+            Ok(())
+        }
         "list-dir" => list_dir::run(&args[2..]),
         "mkdir" => mkdir::run(&args[2..]),
         "pipe-stdin" => pipe_stdin::run(&args[2..]),
@@ -58,6 +64,10 @@ fn main() {
         "read-stdin" => read_stdin::run(),
         "replace-file-content" => replace_file_content::run(&args[2..]),
         "rm" => rm::run(&args[2..]),
+        "stat-file" => {
+            stat_file::run(&args[2..]);
+            Ok(())
+        }
         "touch-file" => touch_file::run(&args[2..]),
         "write-file" => write_file::run(&args[2..]),
         other => {