voidzero-dev · wan9chi · Jul 26, 2026 · Jul 26, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,6 @@
 # Changelog
 
+- **Added** Tasks now run with `VP_RUN=1` set, so tools can tell they are running under `vp run` instead of being invoked directly ([#570](https://github.com/voidzero-dev/vite-task/pull/570)).
 - **Fixed** The task cache now supports much larger automatically tracked input sets without hitting wincode's default 4 MiB sequence preallocation limit ([#554](https://github.com/voidzero-dev/vite-task/pull/554)).
 - **Fixed** npm workspace patterns beginning with `./` now discover matching packages correctly ([vite-plus#2201](https://github.com/voidzero-dev/vite-plus/issues/2201), [#547](https://github.com/voidzero-dev/vite-task/pull/547)).
 - **Fixed** Failures while forwarding output from a started task process no longer incorrectly say the process failed to spawn ([#506](https://github.com/voidzero-dev/vite-task/issues/506)).

diff --git a/crates/vite_task/src/lib.rs b/crates/vite_task/src/lib.rs
@@ -17,4 +17,4 @@ pub use vite_task_graph::{
 };
 /// Re-exports useful for `CommandHandler` implementations.
 pub use vite_task_plan::get_path_env;
-pub use vite_task_plan::{plan_request, plan_request::ScriptCommand};
+pub use vite_task_plan::{MARKER_ENV_NAME, plan_request, plan_request::ScriptCommand};
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/package.json b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/package.json
@@ -0,0 +1,4 @@
+{
+  "name": "vp-run-env",
+  "private": true
+}
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/snapshots.toml b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/snapshots.toml
@@ -0,0 +1,29 @@
+[[e2e]]
+name = "vp_run_env_marks_every_spawned_task"
+comment = """
+Every process a task spawns gets `VP_RUN=1`, so a tool can tell it was started by `vp run` instead of being typed directly.
+
+The parent shell sets `VP_RUN=0` in both steps to show the marker is forced rather than inherited. The cached task also restricts passthrough to `env: ["NODE_ENV"]`, which filters the parent's value out entirely; the marker is set after that filtering, so it survives either way.
+"""
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "print-marker-cached",
+  ], envs = [
+    [
+      "VP_RUN",
+      "0",
+    ],
+  ], comment = "cached task: env passthrough cannot drop the marker" },
+  { argv = [
+    "vt",
+    "run",
+    "print-marker-uncached",
+  ], envs = [
+    [
+      "VP_RUN",
+      "0",
+    ],
+  ], comment = "uncached task: the parent environment flows through, but the marker still wins" },
+]
diff --git a/..._snapshots/fixtures/vp_run_env/snapshots/vp_run_env_marks_every_spawned_task.md b/..._snapshots/fixtures/vp_run_env/snapshots/vp_run_env_marks_every_spawned_task.md
@@ -0,0 +1,23 @@
+# vp_run_env_marks_every_spawned_task
+
+Every process a task spawns gets `VP_RUN=1`, so a tool can tell it was started by `vp run` instead of being typed directly.
+
+The parent shell sets `VP_RUN=0` in both steps to show the marker is forced rather than inherited. The cached task also restricts passthrough to `env: ["NODE_ENV"]`, which filters the parent's value out entirely; the marker is set after that filtering, so it survives either way.
+
+## `VP_RUN=0 vt run print-marker-cached`
+
+cached task: env passthrough cannot drop the marker
+
+```
+$ vtt print-env VP_RUN
+1
+```
+
+## `VP_RUN=0 vt run print-marker-uncached`
+
+uncached task: the parent environment flows through, but the marker still wins
+
+```
+$ vtt print-env VP_RUN ⊘ cache disabled
+1
+```
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/vite-task.json b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/vp_run_env/vite-task.json
@@ -0,0 +1,15 @@
+{
+  "tasks": {
+    "print-marker-cached": {
+      "command": "vtt print-env VP_RUN",
+      "cache": true,
+      "env": ["NODE_ENV"],
+      "input": ["package.json"],
+      "output": []
+    },
+    "print-marker-uncached": {
+      "command": "vtt print-env VP_RUN",
+      "cache": false
+    }
+  }
+}
diff --git a/crates/vite_task_plan/src/envs.rs b/crates/vite_task_plan/src/envs.rs
@@ -11,6 +11,12 @@ use wincode::{SchemaRead, SchemaWrite};
 const SHA256_DIGEST_LEN: usize = 32;
 const SHA256_PREFIX: &str = "sha256:";
 
+/// Name of the environment variable set to `1` in every process a task spawns.
+///
+/// Lets a tool tell that it is running as part of a task rather than having
+/// been invoked directly.
+pub const MARKER_ENV_NAME: &str = "VP_RUN";
+
 /// SHA-256 digest of a fingerprinted environment variable value.
 #[derive(SchemaWrite, SchemaRead, PartialEq, Eq, Clone, Copy)]
 pub struct EnvValueHash([u8; SHA256_DIGEST_LEN]);

diff --git a/crates/vite_task_plan/src/lib.rs b/crates/vite_task_plan/src/lib.rs
@@ -12,6 +12,7 @@ mod ps1_shim;
 use std::{collections::BTreeMap, ffi::OsStr, fmt::Debug, sync::Arc};
 
 use context::PlanContext;
+pub use envs::MARKER_ENV_NAME;
 pub use error::Error;
 pub use execution_graph::{DEFAULT_CONCURRENCY_LIMIT, ExecutionGraph};
 pub use in_process::InProcessExecution;

diff --git a/crates/vite_task_plan/src/plan.rs b/crates/vite_task_plan/src/plan.rs
@@ -31,7 +31,7 @@ use crate::{
     ExecutionItem, ExecutionItemDisplay, ExecutionItemKind, LeafExecutionKind, PlanContext,
     SpawnCommand, SpawnExecution, TaskExecution,
     cache_metadata::{CacheMetadata, ExecutionCacheKey, ProgramFingerprint, SpawnFingerprint},
-    envs::{EnvFingerprints, EnvValueHash},
+    envs::{EnvFingerprints, EnvValueHash, MARKER_ENV_NAME},
     error::{CdCommandError, Error, PathFingerprintError, PathFingerprintErrorKind, PathType},
     execution_graph::{ExecutionGraph, ExecutionNodeIndex, InnerExecutionGraph},
     in_process::InProcessExecution,
@@ -680,6 +680,13 @@ fn plan_spawn_execution(
         }
     }
 
+    // Mark the child as task-spawned. Set after `EnvFingerprints::resolve` has
+    // filtered `spawn_envs`, so a task's `env`/`untrackedEnv` patterns cannot
+    // drop it, and always to `1`, so a stale value in the parent environment
+    // cannot make a task look like it was invoked directly. A prefix
+    // assignment (`VP_RUN=… command`) still wins: those are applied below.
+    spawn_envs.insert(OsStr::new(MARKER_ENV_NAME).into(), OsStr::new("1").into());
+
     // Add prefix envs to spawn envs.
     spawn_envs.extend(prefix_envs.iter().map(|(name, value)| {
         (OsStr::new(name.as_str()).into(), OsStr::new(value.as_str()).into())

diff --git a/..._snapshots/fixtures/additional_env/snapshots/query_tool_synthetic_task_in_user_task.jsonc b/..._snapshots/fixtures/additional_env/snapshots/query_tool_synthetic_task_in_user_task.jsonc
@@ -76,7 +76,8 @@
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
                       "PATH": "<workspace>/node_modules/.bin:<tools>",
-                      "TEST_VAR": "hello_world"
+                      "TEST_VAR": "hello_world",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...s/cache_cli_override/snapshots/query___cache_does_not_override_per_task_cache_false.jsonc b/...s/cache_cli_override/snapshots/query___cache_does_not_override_per_task_cache_false.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...napshots/fixtures/cache_cli_override/snapshots/query___cache_enables_script_caching.jsonc b/...napshots/fixtures/cache_cli_override/snapshots/query___cache_enables_script_caching.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...verride/snapshots/query___cache_enables_task_caching_even_when_cache_tasks_is_false.jsonc b/...verride/snapshots/query___cache_enables_task_caching_even_when_cache_tasks_is_false.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...i_override/snapshots/query___cache_on_task_with_per_task_cache_true_enables_caching.jsonc b/...i_override/snapshots/query___cache_on_task_with_per_task_cache_true_enables_caching.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...pshots/fixtures/cache_cli_override/snapshots/query___no_cache_disables_task_caching.jsonc b/...pshots/fixtures/cache_cli_override/snapshots/query___no_cache_disables_task_caching.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ixtures/cache_cli_override/snapshots/query___no_cache_overrides_per_task_cache_true.jsonc b/...ixtures/cache_cli_override/snapshots/query___no_cache_overrides_per_task_cache_true.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/..._cli_override/snapshots/query_baseline___tasks_not_cached_when_cache_tasks_is_false.jsonc b/..._cli_override/snapshots/query_baseline___tasks_not_cached_when_cache_tasks_is_false.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ts/plan_snapshots/fixtures/cache_keys/snapshots/query_echo_and_lint_with_extra_args.jsonc b/...ts/plan_snapshots/fixtures/cache_keys/snapshots/query_echo_and_lint_with_extra_args.jsonc
@@ -102,7 +102,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ts/plan_snapshots/fixtures/cache_keys/snapshots/query_lint_and_echo_with_extra_args.jsonc b/...ts/plan_snapshots/fixtures/cache_keys/snapshots/query_lint_and_echo_with_extra_args.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ests/plan_snapshots/fixtures/cache_keys/snapshots/query_normal_task_with_extra_args.jsonc b/...ests/plan_snapshots/fixtures/cache_keys/snapshots/query_normal_task_with_extra_args.jsonc
@@ -75,7 +75,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ests/plan_snapshots/fixtures/cache_keys/snapshots/query_synthetic_task_in_user_task.jsonc b/...ests/plan_snapshots/fixtures/cache_keys/snapshots/query_synthetic_task_in_user_task.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/..._snapshots/fixtures/cache_keys/snapshots/query_synthetic_task_in_user_task_with_cwd.jsonc b/..._snapshots/fixtures/cache_keys/snapshots/query_synthetic_task_in_user_task_with_cwd.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ots/fixtures/cache_keys/snapshots/query_synthetic_task_with_extra_args_in_user_task.jsonc b/...ots/fixtures/cache_keys/snapshots/query_synthetic_task_with_extra_args_in_user_task.jsonc
@@ -77,7 +77,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...apshots/fixtures/cache_scripts_default/snapshots/query_script_not_cached_by_default.jsonc b/...apshots/fixtures/cache_scripts_default/snapshots/query_script_not_cached_by_default.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...fixtures/cache_scripts_task_override/snapshots/query_another_task_cached_by_default.jsonc b/...fixtures/cache_scripts_task_override/snapshots/query_another_task_cached_by_default.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...s/fixtures/cache_scripts_task_override/snapshots/query_script_not_cached_by_default.jsonc b/...s/fixtures/cache_scripts_task_override/snapshots/query_script_not_cached_by_default.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...apshots/fixtures/cache_scripts_task_override/snapshots/query_task_cached_by_default.jsonc b/...apshots/fixtures/cache_scripts_task_override/snapshots/query_task_cached_by_default.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ests/plan_snapshots/fixtures/cache_subcommand/snapshots/query_cache_clean_in_script.jsonc b/...ests/plan_snapshots/fixtures/cache_subcommand/snapshots/query_cache_clean_in_script.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ks_disabled/snapshots/query_per_task_cache_true_still_disabled_by_cache_tasks_false.jsonc b/...ks_disabled/snapshots/query_per_task_cache_true_still_disabled_by_cache_tasks_false.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ests/plan_snapshots/fixtures/cache_tasks_disabled/snapshots/query_script_not_cached.jsonc b/...ests/plan_snapshots/fixtures/cache_tasks_disabled/snapshots/query_script_not_cached.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...ures/cache_tasks_disabled/snapshots/query_task_not_cached_when_cache_tasks_is_false.jsonc b/...ures/cache_tasks_disabled/snapshots/query_task_not_cached_when_cache_tasks_is_false.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...res/cache_true_no_force_enable/snapshots/query_script_cached_when_global_cache_true.jsonc b/...res/cache_true_no_force_enable/snapshots/query_script_cached_when_global_cache_true.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...tures/cache_true_no_force_enable/snapshots/query_task_cached_when_global_cache_true.jsonc b/...tures/cache_true_no_force_enable/snapshots/query_task_cached_when_global_cache_true.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...e_enable/snapshots/query_task_with_cache_false_not_cached_despite_global_cache_true.jsonc b/...e_enable/snapshots/query_task_with_cache_false_not_cached_despite_global_cache_true.jsonc
@@ -35,7 +35,8 @@
                     ],
                     "spawn_envs": {
                       "NO_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/"
                   }

diff --git a/...cd_in_scripts/snapshots/query_cd_before_vt_lint_should_put_synthetic_task_under_cwd.jsonc b/...cd_in_scripts/snapshots/query_cd_before_vt_lint_should_put_synthetic_task_under_cwd.jsonc
@@ -73,7 +73,8 @@
                     ],
                     "spawn_envs": {
                       "FORCE_COLOR": "1",
-                      "PATH": "<workspace>/node_modules/.bin:<tools>"
+                      "PATH": "<workspace>/node_modules/.bin:<tools>",
+                      "VP_RUN": "1"
                     },
                     "cwd": "<workspace>/src"
                   }