fix(env): skip remote version fetching for "latest" in prefer-offline mode

[jdx]

Summary

• Adds prefer_offline guard for "latest" versions in resolve_version(), matching the existing guard for fully-qualified versions added in fix(hook-env): skip remote version fetching for uninstalled tools in prefer-offline mode #7976
• Prevents mise env, hook-env, activate, and exec from making network calls when resolving "latest" versions — avoiding hangs with private npm registries

Context

After lockfiles graduated from experimental in v2026.2.0 (#7929), mise env --json with npm:pkg = "latest" and no lockfile entry falls through to a network fetch that prefer_offline mode was intended to prevent. If the private registry holds the TCP connection open (waiting for credentials), mise hangs indefinitely.

PR #7976 fixed this for fully-qualified versions (e.g. "2.3.2") but the "latest" path was not covered. This one-liner closes that gap.

See #8499 for the full root cause analysis.

Fixes #8499

Test plan

• mise env --json with npm:pkg = "latest" and no registry auth no longer makes network calls or hangs
• Existing behavior unchanged when prefer_offline is not set (e.g. mise install still resolves latest from registry)

🤖 Generated with Claude Code

---

Note

Low Risk
Small conditional change to version resolution logic that only affects prefer_offline behavior for latest; low risk but could change expectations for users relying on remote latest lookup in that mode.

Overview
Prevents network access when resolving "latest" in ToolVersion::resolve_version while prefer_offline is enabled, aligning latest behavior with the existing prefer-offline skip for fully-qualified versions.

This adds a guard so hook-env/activate/exec/env won’t call latest_version_with_opts unless explicitly doing a latest-version lookup (opts.latest_versions), avoiding hangs against registries that keep connections open.

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

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the prefer_offline functionality by ensuring that 'latest' tool versions are resolved locally without making network calls when offline mode is active. This change prevents applications like mise env from hanging when encountering private npm registries, aligning the behavior of 'latest' version resolution with that of fully-qualified versions under prefer_offline settings.

Highlights

• Prefer Offline Guard for 'latest' Versions: Implemented a prefer_offline guard within the resolve_version() function to prevent remote fetching of 'latest' tool versions when offline mode is preferred.
• Network Call Prevention: Ensured that mise env, hook-env, activate, and exec no longer make network calls for 'latest' versions when prefer_offline is enabled, addressing potential hangs with private npm registries.
• Consistency with Fully-Qualified Versions: Extended the existing prefer_offline behavior for fully-qualified versions to also cover 'latest' versions, closing a gap identified after lockfiles graduated from experimental.

Changelog

• src/toolset/tool_version.rs
  • Added a check for settings.prefer_offline() before attempting to fetch the latest version from a remote backend.

Activity

• No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a prefer_offline guard when resolving the 'latest' version, specifically in src/toolset/tool_version.rs, to skip remote version fetching when prefer-offline mode is enabled, enhancing performance and reliability. A security audit found no vulnerabilities meeting reporting criteria. Additionally, a suggestion has been made to simplify the logic by removing a now redundant check.

[gemini-code-assist]

This change makes the !is_offline check on line 269 redundant. If settings.prefer_offline() is false, then settings.offline() must also be false, which means is_offline is false and !is_offline is always true in that code path.

Consider simplifying this logic by removing the redundant check. The block from line 266 to 275 could be simplified to:

            if settings.prefer_offline() {
                return build(v);
            }
            if let Some(v) = backend
                .latest_version_with_opts(config, None, opts.before_date)
                .await?
            {
                return build(v);
            }

            if settings.prefer_offline() {
                return build(v);
            }
            if let Some(v) = backend
                .latest_version_with_opts(config, None, opts.before_date)
                .await?
            {
                return build(v);
            }

[greptile-apps]

Greptile Summary

This PR adds a one-line prefer_offline guard to prevent latest_version_with_opts() from being called when resolving "latest" versions in prefer_offline mode. The intent is to stop mise env/hook-env/activate/exec from hanging against private registries.

Key issues found:

• Incomplete fix: The new guard at line 267 blocks the latest_version_with_opts() call, but when no installed version is found the code falls through the if v == "latest" block to list_versions_matching_with_opts() (line 297) and then resolve_prefix() (line 311). Neither of those code paths checks prefer_offline() — list_remote_versions_with_info() in backend/mod.rs only gates on settings.offline() (strict offline). The TCP hang on a private npm registry can therefore still occur via this fallthrough path.
• Misleading comment: The updated comment now says "latest" "still needs remote resolution", which directly contradicts the fix's stated goal and is confusing to future readers.

Confidence Score: 2/5

• The fix is incomplete: it guards only one of two network-call paths for "latest" in prefer_offline mode, so the hang described in `mise env` hangs indefinitely and spawns hundreds of npm processes with private registries — root cause analysis #8499 can still occur via list_versions_matching_with_opts / resolve_prefix.
• The new guard correctly blocks latest_version_with_opts(), but code analysis shows that list_remote_versions_with_info() — called by list_versions_matching_with_opts on line 297 and again inside resolve_prefix on line 311 — only gates on settings.offline(), not settings.prefer_offline(). A v == "latest" path with no installed version will fall through to those network calls in prefer_offline mode, leaving the original bug unfixed.
• src/toolset/tool_version.rs — specifically the fallthrough from the if v == "latest" block to list_versions_matching_with_opts and resolve_prefix without a prefer_offline early-return.

Important Files Changed

Filename	Overview
src/toolset/tool_version.rs	Adds a prefer_offline guard to the "latest" branch of resolve_version, but the code still falls through to list_versions_matching_with_opts (and resolve_prefix) which can make network calls — the fix only partially prevents the hang described in #8499. The updated comment is also misleading.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["resolve_version(v, opts)"] --> B{v == 'latest'?}
    B -- Yes --> C{!opts.latest_versions AND installed version exists?}
    C -- Yes --> D[return installed version ✅]
    C -- No --> E{"!is_offline AND\n(!prefer_offline OR opts.latest_versions)?\n[NEW GUARD]"}
    E -- Yes --> F["latest_version_with_opts()\n🌐 network call"]
    F --> G[return remote latest ✅]
    E -- No --> H["⚠️ Falls through without returning"]
    B -- No --> I{!opts.latest_versions?}
    H --> I
    I -- Yes --> J["list_installed_versions_matching(v)\n(local, no network)"]
    J --> K{match found?}
    K -- Yes --> L[return installed match ✅]
    K -- No --> M{is_offline?}
    M -- Yes --> N[return v as-is ✅]
    M -- No --> O{"prefer_offline AND\nv.matches('.') >= 2?"}
    O -- Yes --> P["return v as-is ✅\n(fully-qualified only)"]
    O -- No --> Q["list_versions_matching_with_opts()\n🌐 NETWORK CALL\n⚠️ 'latest' reaches here in prefer_offline mode!"]
    Q --> R{exact match?}
    R -- Yes --> S[return match ✅]
    R -- No --> T["resolve_prefix()\n🌐 ANOTHER network call\n⚠️ also reached in prefer_offline mode"]

    style H fill:#ffcccc,stroke:#cc0000
    style Q fill:#ffcccc,stroke:#cc0000
    style T fill:#ffcccc,stroke:#cc0000

Loading

Comments Outside Diff (2)

1. src/toolset/tool_version.rs, line 260-311 (link)

   Fix only blocks one of two network call paths for "latest" in prefer_offline mode

   The new guard at line 267 correctly prevents latest_version_with_opts() from being called, but when no installed version is found, the code falls out of the if v == "latest" block and continues to line 297:

   let matches = backend
       .list_versions_matching_with_opts(config, &v, opts.before_date)
       .await?;

   list_versions_matching_with_opts calls list_remote_versions_with_info internally, and that function only gates on settings.offline() (strict offline, line 531 of backend/mod.rs), not settings.prefer_offline(). So for v == "latest" with prefer_offline mode, no installed version, and a private registry that holds the TCP connection open, this code still reaches the network — exactly the hang described in `mise env` hangs indefinitely and spawns hundreds of npm processes with private registries — root cause analysis #8499.

   The same code then falls through to resolve_prefix(config, request, "latest", opts) at line 311, which calls list_versions_matching_with_opts a second time.

   To fully close the gap, an early-return should be added for "latest" when prefer_offline is active and latest_versions is not forced. For example, extend the fully-qualified version guard at line 292:

   if settings.prefer_offline() && !opts.latest_versions
       && (v.matches('.').count() >= 2 || v == "latest")
   {
       return build(v);
   }

   Or add a guarded return build(v) at the end of the if v == "latest" block:

   if v == "latest" {
       if !opts.latest_versions
           && let Some(v) = backend.latest_installed_version(None)?
       {
           return build(v);
       }
       if !is_offline
           && (!settings.prefer_offline() || opts.latest_versions)
           && let Some(v) = backend
               .latest_version_with_opts(config, None, opts.before_date)
               .await?
       {
           return build(v);
       }
       // NEW: avoid fallthrough to list_versions_matching_with_opts in prefer_offline mode
       if settings.prefer_offline() && !opts.latest_versions {
           return build(v);
       }
   }

2. src/toolset/tool_version.rs, line 288-294 (link)

   Updated comment contradicts the PR's stated intent

   The comment now reads:

   Prefix versions like "2" or "latest" still need remote resolution to find e.g. "2.1.0" or the actual latest version number.

   But the PR description says the fix is precisely to prevent remote resolution for "latest" in prefer_offline mode. Adding "latest" to the list of versions that "still need remote resolution" is misleading — it describes what the code actually does (falls through to a network call) rather than what was intended. This comment should either be reverted to its original form or updated to explain that "latest" is handled by the guard above, e.g.:

_{Last reviewed commit: 1ecf269}

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

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.3.4 x -- echo	23.9 ± 0.9	23.1	35.5	1.00
mise x -- echo	24.1 ± 0.7	23.3	35.6	1.01 ± 0.05

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.3.4 env	23.5 ± 0.8	22.6	28.9	1.00
mise env	23.5 ± 0.3	22.7	25.0	1.00 ± 0.04

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.3.4 hook-env	24.0 ± 0.4	23.2	26.8	1.00
mise hook-env	24.3 ± 0.5	23.4	29.1	1.01 ± 0.03

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.3.4 ls	23.2 ± 0.6	22.4	32.7	1.00
mise ls	23.6 ± 0.5	22.8	26.3	1.02 ± 0.03

xtasks/test/perf

Command	mise-2026.3.4	mise	Variance
install (cached)	151ms	151ms	+0%
ls (cached)	83ms	83ms	+0%
bin-paths (cached)	87ms	87ms	+0%
task-ls (cached)	847ms	825ms	+2%