v2026.7.14

This release adds overlay installs for GitHub-based tools, closes a config-trust security gap around default shell arguments, and lands a wide batch of correctness fixes across tasks, lockfiles, npm, Swift, brew casks, and Windows Python.

## Added
- **github:** the GitHub/GitLab/Forgejo release backend now accepts `additional_asset_patterns`, so a single install can overlay multiple release archives from the same tag into one installation directory. Each supplemental artifact is locked and verified (checksums and provenance) on its own, and `--locked` fails if the recorded set no longer matches. This models release layouts like Ollama's optional ROCm archive without making a large payload unconditional. ([#11272](https://github.com/jdx/mise/pull/11272) by @jdx)

  ```toml
  [tools."github:ollama/ollama"]
  version = "latest"
  additional_asset_patterns = ["ollama-linux-amd64-rocm.tgz"]
  ```
- **npm:** new `allow_low_downloads` tool option lets an embedded aube install bypass the weekly-download popularity gate for the requested package only, so curated tools like `bibtex-tidy` and `purty` install again without `npm.shell_out`. Transitive dependencies still hit the gate. ([#11305](https://github.com/jdx/mise/pull/11305) by @jdx)
- **env:** structured env files (`env._.file` loading JSON/YAML/TOML) support an explicit `expand = true` option for shell-style variable expansion, including references to earlier values. See Fixed below for the default-behavior change. ([#11269](https://github.com/jdx/mise/pull/11269) by @jdx)

## Fixed
- **env:** values loaded from JSON/YAML/TOML env files are literal by default again, fixing a regression where every value was shell-expanded when `env_shell_expand` was on. That corrupted literals such as bcrypt-style `$6$salt$hash` and could pull in matching process-environment values. Opt back into expansion with `expand = true`. ([#11269](https://github.com/jdx/mise/pull/11269) by @jdx)
- **python:** `pip` is now usable on fresh Windows installs. mise synthesizes `pip.cmd`/`pip3.cmd` wrappers, adds the install's `Scripts` directory to PATH so pip-installed console scripts resolve, and fixes default-package installation on Windows. ([#11278](https://github.com/jdx/mise/pull/11278) by @JamBalaya56562)
- **github:** `.exe` release assets are now preferred on Windows, so tools that ship both an extensionless and `.exe` binary no longer install the non-runnable one and fail with "cannot find binary path". ([#11257](https://github.com/jdx/mise/pull/11257) by @gologames)
- **github:** a rejected GitHub token (401) now produces an actionable error that names the token source (gh CLI, `github_tokens.toml`, OAuth, env var, etc.) and includes GitHub's response and a remediation hint, instead of a bare `401 Unauthorized`. ([#11236](https://github.com/jdx/mise/pull/11236) by @Marukome0743)
- **backend:** an archive containing a single binary with an OS/arch suffix (e.g. `gdscript-formatter-macos-aarch64`) is now renamed to its clean name on PATH, matching the existing behavior for single-file downloads. ([#11232](https://github.com/jdx/mise/pull/11232) by @Marukome0743)
- **brew:** brew-cask installs handle more real-world casks — completion stanzas and `system_command` in lifecycle blocks are supported, and artifact links into root-owned directories like `/usr/local/bin` now elevate through mise's sudo policy instead of failing with permission errors. Fixes installing `docker-desktop`. ([#11273](https://github.com/jdx/mise/pull/11273) by @jdx)
- **lockfile:** `prefix:` tool requests now honor the locked version on `mise install` instead of silently re-resolving to the newest match. Constrained upgrades via `mise upgrade`/`mise lock --bump` still work. ([#11255](https://github.com/jdx/mise/pull/11255) by @JamBalaya56562)
- **aqua:** cross-platform lockfiles for aqua HTTP packages preserve a reachable `v`-prefixed URL, fixing 404s where an entry locked to another platform's unprefixed URL. ([#11267](https://github.com/jdx/mise/pull/11267) by @jdx)
- **swift:** Swift lockfile entries now record the target Linux distro (`ubuntu24.04`, `fedora39`, `ubi9`, ...) so checksums are no longer verified across mismatched distro tarballs, and `mise lock` writes meaningful entries and re-locks correctly after changing `swift.platform`. ([#11299](https://github.com/jdx/mise/pull/11299) by @jdx)
- **task:** with a git worktree checked out inside the main checkout, mise no longer loads the enclosing monorepo root's tasks into the nested root's namespace. Env, tools, and vars still inherit as before. ([#11283](https://github.com/jdx/mise/pull/11283) by @jdx)
- **task:** changing a task's `run` command, `sources`, or `outputs` now invalidates its cached state, so tasks are no longer incorrectly skipped after such edits. ([#11288](https://github.com/jdx/mise/pull/11288) by @rabadin)
- **task:** a task's source hash is now persisted only after a successful run, so a failed run no longer marks stale sources as up to date. ([#11296](https://github.com/jdx/mise/pull/11296) by @rabadin)
- **completions:** shell completion no longer offers mise's own global flags after a task name (where they aren't valid), and a task flag that shares a name with a mise flag now completes its own values correctly. ([#11284](https://github.com/jdx/mise/pull/11284) by @jdx)
- **npm:** npm package versions with very large numeric components (up to `Number.MAX_SAFE_INTEGER`) now sort correctly, fixing cases where a `0.0.*` build could be picked over a newer stable release. ([#11280](https://github.com/jdx/mise/pull/11280) by @jdx)
- **npm:** aube trust-downgrade failures now surface a clearer explanation, and aube's own progress display no longer competes with mise's output (bumped to 1.33.1). ([#11292](https://github.com/jdx/mise/pull/11292), [#11308](https://github.com/jdx/mise/pull/11308) by @jdx)
- **npm:** aube `allow_builds` is now serialized as a map. ([#11262](https://github.com/jdx/mise/pull/11262) by @jdx)
- **version:** the update-check cache now negative-caches, so machines that can't reach the network (or run a build newer than the latest release) stop re-running the full check — including building an HTTP client and parsing the CA trust store — on every invocation. This is a significant speedup for commands like `mise --version` in those cases. ([#11285](https://github.com/jdx/mise/pull/11285) by @jdx)
- **env:** remaining `std::env::vars()` call sites now use `vars_safe()`. ([#11309](https://github.com/jdx/mise/pull/11309) by @JamBalaya56562)

## Changed
- **usage:** every mise command now declares its effect on the system — read-only, modifies state, or destructive — surfaced in the command reference. This requires usage 4.0 (`min_usage_version` bumped), so shell completions and doc rendering now depend on it. ([#11306](https://github.com/jdx/mise/pull/11306) by @jdx)

## Security
- **config:** the Unix/Windows default file and inline shell-argument settings are now global-only. Because local config is loaded before trust evaluation, an untrusted repository could previously influence how commands from trusted sources were executed. Global config and `MISE_*` environment variables still apply. Reported by @arpitjain099. ([#11293](https://github.com/jdx/mise/pull/11293) by @jdx)

> [!WARNING]
> Breaking change: project-local values for `unix_default_file_shell_args`, `unix_default_inline_shell_args`, `windows_default_file_shell_args`, and `windows_default_inline_shell_args` are ignored in this release. Projects that used these settings to standardize task shells should set `shell` on each task for now. A config-scoped `task_config.shell` replacement is proposed in [#11354](https://github.com/jdx/mise/pull/11354).

## Performance
- **cli:** the clap command tree is no longer rebuilt twice on every invocation. ([#11297](https://github.com/jdx/mise/pull/11297) by @jdx)

## Documentation
- **npm:** documented Socket integrations. ([#11268](https://github.com/jdx/mise/pull/11268) by @jdx)
- **backend:** corrected the `bin_path`/`asset_pattern` template variable docs. ([#11298](https://github.com/jdx/mise/pull/11298) by @jdx)
- Retargeted a dead clap.rs link to docs.rs/clap. ([#11194](https://github.com/jdx/mise/pull/11194) by @Bartok9)
- Added a generated `llms.txt` index for AI agents. ([#11300](https://github.com/jdx/mise/pull/11300) by @jdx)

## Registry
- Added `checkstyle` ([#11287](https://github.com/jdx/mise/pull/11287) by @zeitlinger), `grok` ([#11291](https://github.com/jdx/mise/pull/11291)), and `tak` ([#11307](https://github.com/jdx/mise/pull/11307)) by @jdx.

## New Contributors
* @gologames made their first contribution in [#11257](https://github.com/jdx/mise/pull/11257)

**Full Changelog**: https://github.com/jdx/mise/compare/v2026.7.13...v2026.7.14

## 💚 Sponsor mise

mise is maintained by [@jdx](https://github.com/jdx), an open source developer for [**entire.io**](https://entire.io), the title sponsor of the [jdx.dev](https://jdx.dev) open source tools. Development is funded by sponsors.

If mise saves you or your team time, please consider sponsoring at [jdx.dev](https://jdx.dev/sponsors.html). Individual and company sponsorships keep mise fast, free, and independent.