feat(env): add environment caching with module cacheability support

[jdx]

Summary

• Adds environment caching for mise with encrypted session-scoped storage
• Extends vfox MiseEnvResult with cacheable and watch_files fields for module cacheability
• Adds --fresh-env/-F flag to exec and run commands to bypass cache

Implementation Details

Cache System

• Cache stored at ~/.local/state/mise/env-cache/
• ChaCha20-Poly1305 encryption with session-scoped key
• Key generated on mise activate and exported as __MISE_ENV_CACHE_KEY
• Key is lost when shell session ends (provides security)

Cache Invalidation

Cache invalidates when:

• Config file mtimes change
• Tool versions change
• Settings change
• mise version changes
• TTL expires (default 1h, configurable via env_cache_ttl)
• Module watch_files change

New Settings

env_cache = true  # Enable caching (default: false)
env_cache_ttl = "1h"  # Cache TTL (default: 1h)

Module Cacheability

vfox plugins can now return cache metadata:

return {
    cacheable = true,
    watch_files = {"/path/to/config"},
    env = {{key = "FOO", value = "bar"}}
}

Legacy format (array of env vars) still works and is treated as uncacheable for backward compatibility.

Test plan

• mise run test:e2e test_env_cache - Basic caching tests
• mise run test:e2e test_env_cache_fresh - Tests for --fresh-env flag
• Verify cache directory is created when caching enabled
• Verify cache invalidates on config change
• Manual testing with MISE_ENV_CACHE=1 in shell

🤖 Generated with Claude Code

---

Note

Introduces an encrypted, session-scoped environment cache and integrates it across env resolution, CLI, and settings.

• Implements ChaCha20-Poly1305–encrypted env cache at ~/.local/state/mise/env-cache with TTL (env_cache_ttl), key via __MISE_ENV_CACHE_KEY generated on activate; cache load/save, watch-file mtime validation, and invalidation on config/tool/settings/version changes
• Extends vfox MiseEnv to return {env, cacheable, watch_files}; consumers updated to track cacheability and watch files
• Integrates caching into toolset env computation and PATH; adds --fresh-env to exec/run (and tasks/shims propagation) to bypass cache
• Adds settings env_cache and env_cache_ttl (schema + settings.toml), and includes env cache in cache prune/cache clear
• Updates docs/man/usage and adds e2e tests for env cache and --fresh-env
• Adds dependencies hex and chacha20poly1305

^{Written by Cursor Bugbot for commit 77b1d29. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

This PR adds environment caching to mise to improve performance for nested invocations, using session-scoped encrypted storage and comprehensive cache invalidation mechanisms.

Changes:

• Implements encrypted environment caching system with ChaCha20-Poly1305 encryption and session-scoped keys
• Extends vfox plugin system to support module cacheability metadata via MiseEnvResult structure
• Adds --fresh-env/-F flags to exec and run commands to bypass cache on demand

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/toolset/env_cache.rs	New module implementing core cache system with encryption, TTL, and watch file validation
src/toolset/toolset_env.rs	Integrates cache loading/saving logic into environment computation
src/plugins/vfox_plugin.rs	Updates mise_env to return MiseEnvResponse with cache metadata
crates/vfox/src/hooks/mise_env.rs	Implements MiseEnvResult with backward-compatible legacy format support
src/cli/exec.rs	Adds --fresh-env flag and cache key propagation to exec command
src/cli/run.rs	Adds --fresh-env flag to run command
src/cli/activate.rs	Generates and exports encryption key during shell activation
src/config/env_directive/module.rs	Tracks module cacheability and watch files in environment results
settings.toml	Defines env_cache and env_cache_ttl configuration settings
e2e/env/test_env_cache	Adds end-to-end tests for basic caching functionality
e2e/env/test_env_cache_fresh	Adds tests for --fresh-env flag behavior

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The path separator is hardcoded as : which is Unix-specific. This will not work correctly on Windows where the separator is ;. Use std::path::MAIN_SEPARATOR or a cross-platform approach to join paths.

[Copilot]

Using rand::random() for cryptographic key generation is not cryptographically secure. Use ChaCha20Poly1305::generate_key(&mut OsRng) or a CSPRNG like rand::rngs::OsRng to ensure secure random key generation.

Suggested change

	let key: [u8; 32] = rand::random();
	BASE64_STANDARD.encode(key)
	let key = ChaCha20Poly1305::generate_key(&mut OsRng);
	BASE64_STANDARD.encode(&key)

[Copilot]

Using unsafe to modify environment variables is unnecessary here. While the comment explains the reasoning, std::env::remove_var is safe in Rust and doesn't require an unsafe block. Remove the unsafe wrapper.

Suggested change

	// SAFETY: We're only unsetting a mise-specific env var, not affecting other
	// processes or causing data races
	unsafe {
	std::env::remove_var("__MISE_ENV_CACHE_KEY");
	}
	// We're only unsetting a mise-specific env var, not affecting other
	// processes or causing data races
	std::env::remove_var("__MISE_ENV_CACHE_KEY");

[Copilot]

Using unsafe to modify environment variables is unnecessary here. While the comment explains the reasoning, std::env::remove_var is safe in Rust and doesn't require an unsafe block. Remove the unsafe wrapper.

Suggested change

	// SAFETY: We're only unsetting a mise-specific env var, not affecting other
	// processes or causing data races
	unsafe {
	std::env::remove_var("__MISE_ENV_CACHE_KEY");
	}
	std::env::remove_var("__MISE_ENV_CACHE_KEY");

[Copilot]

If parsing as an array fails, the error message won't clearly indicate this is a legacy format issue. Consider wrapping this with a more descriptive error message using map_err to help users understand the format requirements.

Suggested change

	let env: Vec<EnvKey> = Vec::from_lua(Value::Table(table), lua)?;
	let env: Vec<EnvKey> = Vec::from_lua(Value::Table(table), lua).map_err(|e| {
	LuaError::RuntimeError(format!(
	"Failed to parse legacy MiseEnv hook result as an array of env keys. \
	Expected an array like {{ {{\"KEY\", \"VALUE\"}}, ... }}. Underlying error: {e}"
	))
	})?;

[Copilot]

The version 0.10 of chacha20poly1305 may not be the latest. Consider using a more recent version to benefit from security updates and improvements. Check crates.io for the latest stable version.

Suggested change

	chacha20poly1305 = "0.10"
	chacha20poly1305 = "0.10.1"

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.1.5 x -- echo	15.1 ± 0.4	14.1	16.4	1.00
mise x -- echo	15.3 ± 0.4	14.3	17.3	1.01 ± 0.04

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.1.5 env	15.9 ± 0.6	14.0	17.7	1.00
mise env	16.6 ± 0.6	15.5	22.1	1.05 ± 0.05

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.1.5 hook-env	16.1 ± 0.4	15.1	17.3	1.00 ± 0.04
mise hook-env	16.1 ± 0.5	15.0	18.8	1.00

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.1.5 ls	14.2 ± 0.4	13.2	15.8	1.00
mise ls	14.2 ± 0.4	13.2	15.3	1.00 ± 0.04

xtasks/test/perf

Command	mise-2026.1.5	mise	Variance
install (cached)	82ms	82ms	+0%
ls (cached)	54ms	54ms	+0%
bin-paths (cached)	55ms	55ms	+0%
task-ls (cached)	232ms	233ms	+0%

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Plugin directory mtime doesn't detect file modifications

Medium Severity

The plugin directory path is added to watch_files for cache invalidation, but directory mtimes only change when files are added or removed, not when existing files are modified. This means updating a plugin's source code (like editing hooks/mise_env.lua) won't invalidate the cache, causing stale cached environment values to persist. The comment claims this "ensures cache invalidates when plugin is updated" but that's incorrect for file modifications.