[jdx]

https://entire.io/gh/jdx/mise/trails/762

mise install, mise use, mise run and other commands that only need a version matching a request used to refetch a tool's version list whenever the cached copy was more than an hour old (fetch_remote_versions_cache). Most of those refetches can't change the answer: with the default 24h minimum_release_age, a release published after the list was fetched can't be installed until it is 24h old anyway.

These commands now keep a cached list for the tool's effective release-age cutoff less an hour (the most a versions-host snapshot lags the cache file), clamped to between 1 and 24 hours:

Effective minimum_release_age	List is reused for
default (24h)	23h
"7d" or an absolute date	24h
"6h" (setting, per-tool option or --minimum-release-age)	5h
"2h" or less, "0s", or no cutoff for the tool	1h, as before

The cutoff is the one resolution uses: the global setting, a per-tool minimum_release_age (or the deprecated install_before), minimum_release_age_excludes, the built-in default, and the --minimum-release-age flag on install/use.

For example, with the default cutoff:

mise install          # fetches node's list
# two hours later
mise install          # reuses it; no request
mise outdated         # refetches it, as before

What keeps the 1h window

• Commands that report what is newest: mise outdated, mise upgrade, mise ls-remote, mise lock and mise latest. latest joins the other four in the remote-fetch command list, so under prefer_offline it also gets the full fetch_remote_versions_timeout budget, like they do.
• Lists that don't date every version. A release-age cutoff admits an undated release as soon as it appears, so a stale undated list really could hide a release the cutoff allows.
• Any setup where you set fetch_remote_versions_cache yourself. An explicit value applies to every command, as it does today. Its default is now documented as 1h rather than stored as one, so mise can tell an explicit 1h from the default.

Prefer-offline commands (shims, activate, exec, env, ls) and --offline are unchanged. They still use any cached list, whatever its age.

The install-time refresh for latest when nothing installed matches (#14457) uses the same window. Before, it only took the cutoff shortcut for a list less than 1h old. Now it takes it for a list less than the window old, and the snapshot-lag margin from #14457 still applies. Within one command, a list adopted for a request with a long window is not reused for a later request whose window is shorter (for example --tool-option minimum_release_age=0s).

Not changed: backend-specific caches that hold a single "latest" pointer or non-list data (npm dist-tags, PyPI latest, asdf latest-stable, aqua tags and bin paths, the tool catalog), GitHub/GitLab/Forgejo release caches, and the multi-tool versions index all stay on fetch_remote_versions_cache. Most aren't read when the outer list is fresh. A pointer isn't covered by the dated-list argument, so extending those is left to a separate change.

Tests

• Unit: the window for 30m, 2h, 6h, 24h, 7d, a cutoff in the future, the default, per-tool and global cutoffs, 0s, and an explicit fetch_remote_versions_cache. Also list reuse for dated, undated, short-cutoff and explicit-setting lists, a later request with a shorter window in the same process, and the CacheManager helpers.
• e2e test_version_list_release_age_window: against a local versions host, mise install --dry-run reuses a 2h-old list. It refetches under MISE_FETCH_REMOTE_VERSIONS_CACHE=1h, MISE_MINIMUM_RELEASE_AGE=90m, or when the list is 25h old. mise outdated refetches a 2h-old list.

🤖 Generated with Claude Code

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5-5; version: 2.1.295.

---

Note

Medium Risk
Changes when remote version lists are considered fresh affect install resolution and network behavior across commands; logic is gated by release-age settings and command type with extensive tests.

Overview
Install-style commands (mise install, use, run, etc.) no longer refetch remote version lists every hour when the default applies. They can reuse a cached list for up to the tool’s effective minimum_release_age minus one hour (clamped 1–24h, e.g. 23h with the default 24h cutoff), but only when every version in the list has parseable release dates.

“Newest” commands (outdated, upgrade, ls-remote, lock, and newly classified latest) still refresh after fetch_remote_versions_cache (documented default 1h; the setting is now optional so mise can distinguish unset from an explicit 1h). Setting fetch_remote_versions_cache yourself applies that TTL everywhere.

CacheManager gains adopt_file_if_fresh_for and forget_memory_older_than so a list adopted for a long window isn’t served from memory to a later request with a shorter cutoff. install/use record --minimum-release-age before listing versions.

Docs, schema, and an e2e test cover the split refresh behavior.

^{Reviewed by Cursor Bugbot for commit 94f58da. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features
  • Version-list caching now varies by command: install and version-matching operations can reuse lists based on minimum_release_age, while commands that report the newest versions refresh lists after the configured cache duration (one hour by default).
  • Offline-preferring commands continue using cached data regardless of age. Setting fetch_remote_versions_cache applies its duration across commands.
• Documentation
  • Updated caching guidance to explain the different refresh rules and defaults.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: de2bfe0b-d219-41fc-a9eb-cafe758430ee

📥 Commits

Reviewing files that changed from the base of the PR and between 94f58da and 94f58da.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 65b21b7d-1a4d-4797-a384-a272c8e52046

📥 Commits

Reviewing files that changed from the base of the PR and between 278ce34 and 94f58da.

📒 Files selected for processing: 6

• crates/mise-util/src/cache.rs
• docs/cache-behavior.md
• docs/continuous-integration.md
• settings.toml
• src/backend/mod.rs
• src/install_before.rs

🚧 Files skipped from review as they are similar to previous changes: 3

• docs/continuous-integration.md
• docs/cache-behavior.md
• settings.toml

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

📝 Walkthrough

Version-list caching now uses release-age windows for eligible version-selection commands. Remote-fetch commands use fetch_remote_versions_cache. CLI cutoffs flow into backend cache adoption, which requires cached versions to have parseable dates.

Changes: Release-age version-list caching

Layer / File(s)	Summary
Cache freshness policy crates/mise-util/src/cache.rs, crates/mise-util/src/network.rs, crates/mise-util/src/env.rs, src/install_before.rs	Cache adoption accepts a caller-provided freshness duration and tracks the timestamp of adopted files. Network settings and command type determine whether release-age windows apply. The window is clamped to 1–24 hours.
CLI and backend integration src/cli/install.rs, src/cli/use.rs, src/backend/mod.rs, e2e/cli/test_version_list_release_age_window	Install and use commands record CLI release-age cutoffs. Backend cache adoption applies the eligible window and requires a nonempty list with parseable dates for every version. Tests cover reuse and refresh behavior.
Cache policy settings and documentation settings.toml, schema/mise.json, docs/cache-behavior.md, docs/continuous-integration.md, docs/dev-tools/index.md	The setting documentation and schema describe the default fetch-cache duration. The documentation distinguishes version-matching commands from newest-version commands and explains the release-age window.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant InstallBefore
  participant Backend
  participant CacheManager
  CLI->>InstallBefore: Store resolved minimum-release-age cutoff
  Backend->>InstallBefore: Get applicable release-age window
  Backend->>CacheManager: Adopt cached versions within freshness limit

Loading

Suggested reviewers: risu729

Merge Risk: ⚪ Minimal · up to 94f58

The newest-version commands retain their configured cache duration, and no merge-blocking issue is established.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 75.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 7 files. (3 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: reusing cached version lists within the tool's release-age window.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 75.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 7 files. (3 skipped: 3 unsupported.)

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new blocking issues remain.

Summary

This PR reuses fully dated version lists for the tool's release-age window while keeping shorter refresh periods for commands that report newest versions.

• Matching-version requests reuse dated version lists for longer.

_{Reviews (3) · Last reviewed commit: "fix(install): only drop in-memory versio..." · Reviewed by Greptile}

[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.}

^{Reviewed by Cursor Bugbot for commit 278ce34. Configure here.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
env	█▁	27,975,149 → 27,907,170	-0.24%	19.45 → 19.53ms	+0.43%
hook-env	█▁	30,262,742 → 30,177,230	-0.28%	21.00 → 20.65ms	-1.64%
ls	█▁	32,138,240 → 32,096,652	-0.13%	21.53 → 21.77ms	+1.08%
registry	█▁	40,255,575 → 40,213,094	-0.11%	18.11 → 17.76ms	-1.93%
startup	█▁	11,265,645 → 11,264,334	-0.01%	12.14 → 12.27ms	+1.01%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{94f58dacb1de vs 90ca0b36b84a · measured on the runner, not pushed to the history.}