bug: Homebrew Base upgrade can leave a stale base-cli in the managed venv #2596

Problem

A Homebrew Base upgrade can leave the persistent managed project virtual environment on an older base-cli, even though the newly installed Base release declares a newer test requirement. The installation then appears present but fails the verified project-runtime check and blocks normal project tests.

Observed on 2026-10-16:

• Homebrew Base is 1.10.5.
• The installed release manifest declares base-cli==0.5.1.
• The persistent managed environment at ~/.base.d/base/.venv still contains base-cli==0.4.3.
• basectl check base --verify-project-runtime reports the missing or mismatched base-cli==0.5.1 requirement.
• basectl test base is then blocked before test execution by the manifest/test-requirements trust and runtime gates.

This is an upgrade-path/release usability defect, not a bad 1.10.5 manifest: the packaged manifest and requirements file agree. The gap is that a manual brew upgrade does not itself reconcile the existing managed environment, while the ordinary setup diagnostics can describe an installed package without making the stale-version mismatch obvious.

Impact

Users who upgrade Base through the documented Homebrew path can retain stale dependency state and receive a late failure from check or test. They need to discover and run an additional setup/reconciliation step, and the failure message does not clearly connect the stale environment to the completed Base upgrade.

Resolution

Implemented and merged in #2608 (a409c3eb). The fix:

• reconciles installed Python packages against exact declared requirements, including stale base-cli versions;
• makes basectl update run clean Homebrew setup after every Homebrew upgrade, including an unchanged formula version;
• documents the direct brew upgrade plus basectl setup contract;
• adds actionable mismatch diagnostics, focused regression coverage, and release-train BOM validation.

Acceptance criteria

• The supported Homebrew upgrade/setup contract is documented, and basectl update always reconciles the managed runtime.
• The stale-base-cli reconciliation regression is covered at the setup boundary without requiring manual dependency installation outside the supported setup path.
• An installed wrong version produces an actionable mismatch and fix instruction.
• The direct-brew upgrade and basectl update behaviors are documented and covered by focused setup/update tests.
• The exact dependency-version assertion is enforced by the release gate and the Homebrew rehearsal.
• The resulting contract is available for the broader N-1 to N matrix in #2562.

Follow-up disposition

The full end-to-end consumer scenario—seed a previous-version managed environment, perform the N-1 to N Homebrew upgrade, verify the installed version, run basectl check base --verify-project-runtime, and prove basectl test base reaches the declared command—is intentionally deferred to #2562. That issue already owns the Homebrew consumer matrix and state-preservation evidence, so no separate follow-up issue is needed.

Related

• #2562 — broader Homebrew consumer N-1 to N upgrade/state-preservation matrix.
• Fail clearly when the installed base-cli provider is incompatible #1853 — prior provider-incompatibility diagnostics work.