cask: gate auto-updates behind opt-in

[MikeMcQuaid]

• switch auto_updates true upgrades to HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS so users keep the current behavior until Homebrew 5.2.0
• keep hidden HOMEBREW_NO_UPGRADE_AUTO_UPDATES_CASKS support for developer overrides and reject conflicting env settings early in brew upgrade
• ignore bad bundle versions such as 0.0 so broken Info.plist metadata does not trigger false upgrades

Fixes #21981

---

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests (excluding integration tests) for your changes? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes.

Used OpenAI Codex with local editing, testing and review.

---

[Copilot]

Pull request overview

This PR changes Homebrew Cask’s upgrade behavior so auto_updates true casks are only auto-upgraded when users explicitly opt in (or when running as a developer), while also hardening version-detection to avoid false upgrade prompts from broken app bundle metadata.

Changes:

• Introduces HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS (opt-in) and keeps HOMEBREW_NO_UPGRADE_AUTO_UPDATES_CASKS as a hidden override, with early conflict validation.
• Updates cask outdated detection to ignore known-bad bundle versions (e.g., 0.0) when evaluating auto-updating apps.
• Updates manpage/docs and adds/adjusts unit tests around the new env behavior and bundle-version edge case.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
manpages/brew.1	Documents the new opt-in env var and removes the old env var from the public manpage.
Library/Homebrew/test/env_config_spec.rb	Adds tests for the new upgrade_auto_updates_casks? env logic and conflict handling.
Library/Homebrew/test/cask/upgrade_spec.rb	Stubs new env gate in tests; adds a regression test for conflicting env vars raising in brew upgrade.
Library/Homebrew/test/cask/cask_spec.rb	Adds regression coverage for ignoring a bad bundle version (0.0) when short version is missing.
Library/Homebrew/manpages.rb	Hides env vars marked hidden: from generated env var docs.
Library/Homebrew/env_config.rb	Adds the new env var, hides the old one, and implements upgrade_auto_updates_casks?.
Library/Homebrew/cask/upgrade.rb	Forces early evaluation of env var conflict to error consistently before cask selection.
Library/Homebrew/cask/cask.rb	Gates auto-updates upgrades behind the new opt-in and ignores bad bundle versions in bundle metadata comparisons.
docs/Manpage.md	Reflects public env var docs changes (new opt-in var; old hidden var removed).
docs/FAQ.md	Updates FAQ guidance to mention the new opt-in env var and planned default change in 5.2.0.

---

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

[bevanjkay]

I think we should expand this to knock out versions from installed_short_version, but I'm happy to take a look at this in a follow up PR with some other additional logic (probably on Monday).

[MikeMcQuaid]

@bevanjkay Aye sounds good. Less pressing now it's not applying to everyone any more.