feat(ipc): runner ↔ tool IPC channel with disableCache

Add the runner-aware IPC protocol, embedded Node client addon, execution-time server lifecycle, and disableCache handling.

The protocol ships with the single disableCache verb; getEnv/getEnvs land with env tracking (#430) and ignoreInput/ignoreOutput with auto output tracking (#431), each alongside the runner logic that consumes them.

Co-Authored-By: OpenAI <codex@openai.com>

Author: wan9chi

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- **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))
 - **Fixed** The task cache is now stored in a per-schema-version subdirectory (e.g. `node_modules/.vite/task-cache/v13/`), so switching between branches that pin different Vite+ versions no longer fails with `Unrecognized database version`. Each version keeps its own cache directory; a cache from a different version is ignored rather than aborting the run ([#433](https://github.com/voidzero-dev/vite-task/pull/433))

Cargo.lock

@@ -86,6 +86,9 @@ libc = "0.2.185"
 libtest-mimic = "0.8.2"
 memmap2 = "0.9.7"
 monostate = "1.0.2"
+napi = "3"
+napi-build = "2"
+napi-derive = "3"
 native_str = { path = "crates/native_str" }
 nix = { version = "0.31.2", features = ["dir", "signal"] }
 ntapi = "0.4.1"
@@ -150,8 +153,12 @@ vite_shell = { path = "crates/vite_shell" }
 vite_str = { path = "crates/vite_str" }
 vite_task = { path = "crates/vite_task" }
 vite_task_bin = { path = "crates/vite_task_bin" }
+vite_task_client = { path = "crates/vite_task_client" }
+vite_task_client_napi = { path = "crates/vite_task_client_napi", artifact = "cdylib", target = "target" }
 vite_task_graph = { path = "crates/vite_task_graph" }
+vite_task_ipc_shared = { path = "crates/vite_task_ipc_shared" }
 vite_task_plan = { path = "crates/vite_task_plan" }
+vite_task_server = { path = "crates/vite_task_server" }
 vite_workspace = { path = "crates/vite_workspace" }
 vt100 = "0.16.2"
 wax = "0.7.0"
@@ -169,6 +176,7 @@ ignored = [
   # These are artifact dependencies. They are not directly `use`d in Rust code.
   "fspy_preload_unix",
   "fspy_preload_windows",
+  "vite_task_client_napi",
 ]
 
 [profile.dev]

Cargo.toml

@@ -43,16 +43,27 @@ 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_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

@@ -1,6 +1,7 @@
 use std::{process::ExitStatus, time::Duration};
 
 use vite_path::RelativePathBuf;
+use vite_task_server::Error as IpcServerError;
 
 use super::cache::CacheMiss;
 
@@ -43,6 +44,12 @@ pub enum ExecutionError {
     /// Creating the post-run fingerprint failed after successful execution.
     #[error("Failed to create post-run fingerprint")]
     PostRunFingerprint(#[source] anyhow::Error),
+
+    /// 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.
+    #[error("Failed to set up task communication")]
+    IpcServerBind(#[source] std::io::Error),
 }
 
 #[derive(Debug, Clone)]
@@ -76,6 +83,14 @@ pub enum CacheNotUpdatedReason {
     /// (its `input` config includes auto-inference). Task ran but cannot
     /// be cached without tracked path accesses.
     FspyUnsupported,
+    /// The runner's IPC server failed during execution, so the collected
+    /// reports may be incomplete. Caching such a run would risk stale
+    /// inputs/outputs on the next hit. Carries the underlying error for
+    /// user-facing reporting.
+    IpcServerError(IpcServerError),
+    /// A runner-aware tool explicitly requested that this run not be cached
+    /// (e.g. vite dev-server, a watch task).
+    ToolRequested,
 }
 
 #[derive(Debug)]