Preserve cask backups across lifecycle phases

[MikeMcQuaid]

• Share a private 0700 directory for one cask operation so sandbox cleanup cannot delete data awaiting restoration.
• Retain the directory on failure and report its path for recovery.
• Keep command scratch space isolated and clean up after success.

Fixes #24293

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include brew benchmark results.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

Codex with GPT 6 Astra at Extra High effort, with local review and testing.

---

Summary by CodeRabbit

• New Features

  • Cask install steps can use a private temporary directory shared across phases of an upgrade or reinstall, allowing backups to be restored later.
  • Temporary files are removed after successful operations. If an operation fails, they’re retained and their location is reported.
  • A move step fails if its expected backup is missing, including when if_path_exists is used.

• Documentation

  • Clarified temporary directory behaviour across upgrades, reinstalls, and separate uninstall and install commands.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b9a7d8cb-372e-4e2c-9dcc-a9296a0bce56

📥 Commits

Reviewing files that changed from the base of the PR and between d14629c and 9eaf55d.

📒 Files selected for processing: 3

• Library/Homebrew/install_steps.rb
• Library/Homebrew/test/cask/lifecycle_temp_spec.rb
• docs/Cask-Cookbook.md

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

📝 Walkthrough

Cask install steps now use private temporary storage for lifecycle backups. Install steps track backup moves and detect missing backups. Lifecycle operations share storage during upgrades and reinstalls, then remove it after success or retain it after failure.

Changes: Cask temporary storage lifecycle

Layer / File(s)	Summary
Pass temporary paths and track backups Library/Homebrew/cask/cask.rb, Library/Homebrew/cask_artifact.rb, Library/Homebrew/cask/artifact/install_steps.rb, Library/Homebrew/install_steps.rb	Each cask lazily creates temporary storage under HOMEBREW_TEMP. Install-step contexts receive its path, and Runner#root_path uses it to resolve temp. Moves within the temporary directory create or remove backup markers. A move fails if its source is missing and a marker shows that a backup was expected.
Manage temporary storage across lifecycle operations Library/Homebrew/cask/installer.rb, Library/Homebrew/cask/upgrade.rb	Install, uninstall, zap, and upgrade track completion and clean temporary storage. Reinstall and upgrade preserve temporary state across cask replacement. Failed operations retain temporary files.
Validate and document lifecycle sharing Library/Homebrew/test/cask/lifecycle_temp_spec.rb, docs/Cask-Cookbook.md	Specs check directory reuse, permissions, cleanup, and retention after restoration failure or a missing backup. The cookbook documents sharing across upgrade or reinstall phases and separate storage for separate uninstall and install commands.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 9eaf5

The inspected upgrade and restoration paths preserve the intended backup behavior. No identified issue remains that should block merging after normal checks.

Security architecture risk: 🔵 Low · up to 9eaf5

The private directory improves backup isolation and recovery without a demonstrated increase in filesystem authority. Residual risk concerns lifecycle correctness under abrupt interruption and concurrent operations, which were not fully established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated exposure is local cask lifecycle data and its recovery directory under the executing user's temporary root. The changed producer supplies an internally allocated path, rather than introducing a remote input, service identity, or arbitrary new filesystem root.

Security Findings and Attack Paths

• inferred — No introduced sandbox escape or additional privileged operation was substantiated in the inspected path. Cask-authored steps still pass through the existing Runner and sandbox controls; the new behavior changes backup location and lifetime, not privileged-step eligibility.

Trust Boundaries and Controls

• observed — The existing install-hook sandbox rules permit writes beneath HOMEBREW_TEMP, covering the cask directory and its markers. The privileged-step broker continues to accept only predeclared privileged indices in increasing order and re-evaluates guards in the parent rather than trusting the child.

Resilience and Maintainability Implications

• inferred — Backup movement and marker publication are separate operations. An ordinary marker-write exception reaches failure handling, which retains storage; an unmarked but intact backup can still be restored by its normal move. Silent loss would require additional disappearance or another unsupported recovery sequence, so the publication window is not retained as a demonstrated PR regression. Hard-stop reconciliation and concurrent same-cask ownership remain coverage gaps.

Pre-merge checks: 4

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: preserving cask backup data across lifecycle phases.
Linked Issues check		Issue #24293 requires cask lifecycle backups to survive sandbox cleanup and remain available for restoration. Cask::Cask now provides private 0700 temporary storage, InstallStepsContext receives…
Out of Scope Changes check		The changes stay within Issue #24293. They add shared cask lifecycle temporary storage, sandbox context propagation, missing-backup detection, failure retention, success cleanup, and focused documenta…

Full details: Linked Issues check

Explanation

Issue #24293 requires cask lifecycle backups to survive sandbox cleanup and remain available for restoration. Cask::Cask now provides private 0700 temporary storage, InstallStepsContext receives it through the sandbox context, and the lifecycle code retains it after failure and reports its path. install_steps.rb records backups and raises Expected cask backup is missing when a guarded restore move loses an expected backup. The lifecycle specs cover upgrade, reinstall, failure retention, missing backups, successful cleanup, and separate operation isolation. The changes retain sandbox execution.

Full details: Out of Scope Changes check

Explanation

The changes stay within Issue #24293. They add shared cask lifecycle temporary storage, sandbox context propagation, missing-backup detection, failure retention, success cleanup, and focused documentation and tests. These changes directly support backup preservation and restoration reliability.

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

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