Support pinning casks

[MikeMcQuaid]

• brew pin should cover casks now that upgrades skip both package types.
• Cask pin records keep list, info and upgrade output consistent.
• auto_updates true casks need a warning because app updaters bypass Homebrew.

Fixes #12425
Fixes #11860
Fixes #4898

---

• 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? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• 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. Non-maintainers may only have one AI-assisted/generated PR open at a time.

OpenAI Codex 5.5 xhigh with local review and testing

---

[Copilot]

Pull request overview

Adds first-class pin/unpin support for casks so brew pin, brew unpin, brew list --pinned, brew info, brew upgrade, brew uninstall, brew reinstall, brew bundle, and the cask migrator all treat cask pins symmetrically with formula pins, including a warning that auto_updates true casks may still self-update outside Homebrew.

Changes:

• New Cask::Cask#pin/unpin/pinned?/pinnable?/pinned_version/pin_path API backed by symlinks under a new HOMEBREW_PINNED_CASKS directory; plus serialization (to_h, fixtures) and migrator handling.
• pin/unpin/list --pinned commands extended with --formula/--cask switches; upgrade/uninstall/reinstall skip pinned casks (with summaries/warnings); bundle excludes pinned casks from outdated/greedy checks.
• Documentation, manpage, and bash/zsh/fish completions updated to reflect the new behavior and switches.

Reviewed changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
Library/Homebrew/cask/cask.rb	Adds pin/unpin/pinned?/pinnable?/pinned_version/pin_path APIs and includes pin state in to_h/outdated_info.
Library/Homebrew/cask/upgrade.rb	Filters pinned casks out of upgrades and reports them via summary/opoo/ofail.
Library/Homebrew/cask/uninstall.rb	Refuses to uninstall pinned casks unless forced (then unpins).
Library/Homebrew/cask/migrator.rb	Moves the cask pin symlink when migrating to a new token.
Library/Homebrew/cask/info.rb	Emits the new pinned-cask metadata line in cask info output.
Library/Homebrew/cmd/pin.rb	Accepts casks, adds --formula/--cask, warns on auto_updates true.
Library/Homebrew/cmd/unpin.rb	Accepts casks via the same new switches.
Library/Homebrew/cmd/list.rb	Rewrites --pinned to combine formulae+casks; drops --pinned/--cask conflict.
Library/Homebrew/cmd/upgrade.rb	Adds pinned_casks to FinalUpgradeSummary and renders a new pinned-cask section.
Library/Homebrew/cmd/uninstall.rb	Refuses to zap pinned casks unless forced.
Library/Homebrew/cmd/reinstall.rb	Skips pinned casks in reinstall with an error message.
Library/Homebrew/cmd/info.rb	Renames formula_pinned_time to generic pin_path_mtime and emits cask pin metadata.
Library/Homebrew/bundle/cask.rb	Excludes pinned casks from outdated/greedy bundle checks.
Library/Homebrew/mcp_server.rb	Updates upgrade description string to match new wording.
Library/Homebrew/startup/config.rb (+ test stub)	Defines HOMEBREW_PINNED_CASKS.
Library/Homebrew/test/*	Adds specs for pinning/unpinning, list, info, upgrade summary, reinstall/uninstall guards, migrator, bundle behavior.
Library/Homebrew/test/support/fixtures/cask/everything*.json	Adds pinned/pinned_version fields.
Library/Homebrew/test/spec_helper.rb	Cleans up HOMEBREW_PINNED_CASKS between tests.
docs/Manpage.md, docs/FAQ.md, docs/Versions.md, manpages/brew.1	Documentation updates for cask pinning.
completions/bash/brew, completions/fish/brew.fish, completions/zsh/_brew	New --formula/--cask completions and updated descriptions for pin/unpin/list/upgrade.

---

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

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 5 comments.