fix(desktop): clarify CLI runtime setup

[atishpatel]

Why

Installing the Codex, Claude, or Goose desktop app does not install the command-line harness Buzz needs. The current UI makes that distinction unclear, links some missing-CLI states to adapter documentation, and can report a successful install from the installer exit code even when runtime discovery still fails. On Windows, Buzz also invokes Goose's Bash installer, which writes the executable somewhere Buzz does not discover.

What

• distinguish missing vendor CLIs from missing or outdated ACP adapters in runtime metadata and UI guidance
• link Codex, Claude Code, and Goose missing-CLI states to their official CLI installation documentation
• explain in Settings, onboarding, and agent configuration that the desktop app alone is not sufficient
• use Goose's official PowerShell installer on Windows
• refresh PATH and rediscover the requested runtime after installation, keeping the control retryable if the runtime is still unavailable
• add Rust and Playwright regression coverage for Windows installer selection, CLI/adapter guidance, false-success prevention, verified installs, and onboarding copy

Risk Assessment

Medium. This changes desktop onboarding and runtime installation behavior. Successful installs now require the runtime catalog to verify availability; previously hidden discovery failures will surface as actionable errors instead of a false success state.

References

• Codex CLI installation
• Claude Code installation
• Goose installation
• Follow-up to fix(desktop): fix Windows PATH clobber and .cmd shim EINVAL #2563 and fix(desktop): suppress Windows console flashes and reject WSL bash alias #2587

Validation

• just desktop-typecheck
• just desktop-test — 3,455 passed
• focused Rust post-install verification tests
• focused Playwright Doctor/onboarding coverage (in progress; CI and local sequential rerun will provide final results)

Generated with Codex

[wpfleger96]

hey @atishpatel — consolidated review feedback from two independent passes at 77ac443. One important item, the rest minor/nits (flagging everything for completeness, so weigh accordingly). The core of the change is solid: deriving success from the verified step results instead of installer exit codes is the right fix for the false-success state, the 05/05b specs pin both sides of the new contract, and the CLI-vs-adapter guidance split reads cleanly. We also verified all four vendor doc URLs resolve and that the Goose PowerShell installer honors CONFIGURE=false with the escaping as written (the command runs through Git Bash, so \$env:CONFIGURE reduces to a literal $ for PowerShell — correct).

1. (important, flagged independently by both reviewers) AgentDefinitionDialog.tsx:628-634 branches on selectedRuntime.id === "buzz-agent" to decide whether not_installed means "CLI is missing." That's a hardcoded harness-ID check in render code, which desktop/src/features/agents/AGENTS.md rule 1 explicitly rules out — harness capability facts have exactly one source, the Rust runtime catalog. It also duplicates runtime semantics in the UI: the next bundled/non-vendor runtime would incorrectly be described as missing a CLI unless another ID exception gets added. Worth noting the cli_missing branch and the vendor not_installed branch already produce byte-identical strings, so exposing the fact from the catalog (or a named guidance kind on AcpRuntimeCatalogEntry) removes both the rule violation and the duplication in one move.

2. (minor) post_install_verification.rs calls the full discover_acp_runtimes(), whose probe phase spawns auth probes (10s timeout each) for every available runtime — verification only needs the phase-1 availability classification for the one runtime being installed. On a machine with claude and goose already signed in, every install click pays up to ~10s of dead probe time inside the blocking task. A probe-free availability lookup would fix it.

3. (minor) The Goose Windows installer is pinned to the mutable main branch (raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1) while Unix pulls from the stable release. Looks unavoidable today — the stable release doesn't ship download_cli.ps1 (we checked, it 404s) — but it means the script's env contract can drift under Buzz without a Goose release. Deserves a comment in the catalog naming that constraint, and ideally an upstream ask to attach the .ps1 to stable so both platforms pin the same way.

4. (minor) In DoctorSettingsPanel.tsx, an available but logged-out/config-invalid runtime still gets an action labeled "CLI install guide" — at that point the user needs sign-in or config repair, not installation. "CLI setup guide," or only showing install guidance for unavailable states, would be more accurate.

5. (nit) post_install_verification.rs interpolates the availability enum with {status:?}, so users see Debug output like NotInstalled verbatim in the error text. A small display mapping would read better.

6. (nit) SetupStep.tsx:387-392 — the cli_missing and not_installed branches return the identical string; could collapse to one condition.

7. (nit) Two unrelated blank-line deletions in AgentDefinitionDialog.tsx (around the effect at ~415/424) are pure diff noise.

Item 1 is the only merge-blocker from our side. CI is fully green at head.

[atishpatel]

🤖 Addressed all seven review items in f19b483 (included in current merge head 9d1faf2):

1. Removed the AgentDefinitionDialog runtime-ID exception. The Rust catalog now exposes requires_external_cli (derived from KnownAcpRuntime metadata), the IPC/TypeScript projection carries it, and render code uses that catalog fact for CLI-missing guidance.
2. Extracted reusable phase-1 runtime discovery and changed post-install verification to query only the installed runtime without running catalog-wide authentication probes.
3. Documented why Goose Windows intentionally uses the official mutable main-branch PowerShell script: the stable release currently publishes only the Unix installer. No upstream issue was opened from this PR.
4. Renamed the Doctor action to “CLI setup guide,” which remains accurate for install, sign-in, and configuration-repair states.
5. Replaced Rust Debug enum output such as NotInstalled with human-readable availability labels in verification errors.
6. Collapsed the identical cli_missing and not_installed onboarding detail branches into one condition.
7. Restored the two unrelated blank lines in AgentDefinitionDialog to remove diff noise.

The branch was also merged with current origin/main; GitHub CI is the validation gate for head 9d1faf2.