[Bug] Desktop emits a setup payload buzz-acp cannot parse — missing_binary hard-fails the agent into a restart loop
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Summary
`buzz-acp` rejects a `BUZZ_ACP_SETUP_PAYLOAD` that Buzz Desktop itself produces. Desktop serialises six requirement surfaces; the harness's `RequirementPayload` enum accepts five. `missing_binary` is the odd one out, so any managed agent whose command cannot be resolved exits immediately at startup instead of entering the setup-listener mode the payload exists to trigger.
The user-visible result is the opposite of the intended nudge: a red error badge and a restart loop, with no indication that the actual problem is an unresolvable binary.
## The mismatch (both sides on `main`)
Desktop serialises it — `desktop/src-tauri/src/managed_agents/runtime.rs:667`:
```rust
Requirement::MissingBinary { command } => serde_json::json!({
"surface": "missing_binary",
"command": command,
}),
```
Produced whenever a custom/unknown harness command fails to resolve — `desktop/src-tauri/src/managed_agents/readiness.rs:423`:
```rust
let Some(rt) = runtime else {
// Unknown/custom command — check that the binary is actually resolvable.
if crate::managed_agents::resolve_command(&effective.effective_command).is_none() {
return vec![Requirement::MissingBinary {
command: effective.effective_command.clone(),
}];
}
```
The harness cannot represent it — `crates/buzz-acp/src/setup_mode.rs:92`:
```rust
#[serde(tag = "surface", rename_all = "snake_case")]
pub(crate) enum RequirementPayload {
NormalizedField { field: String },
EnvKey { key: String },
CliLogin { .. },
CliConfigInvalid { .. },
GitBash,
}
```
Five variants, no `MissingBinary`. `SetupPayload::from_raw_env_value` (`setup_mode.rs:231`) fails the whole parse, and `lib.rs:1342` turns that into a fatal startup error.
## Reproduction
1. Create a managed agent whose `agent_command` is not resolvable from the environment Buzz Desktop launches with — e.g. a custom harness installed in a virtualenv that is on your login shell `PATH` but not the GUI `PATH`.
2. Start the agent.
3. It exits immediately. The agent log contains only:
```
=== starting () at 2026-08-03T04:35:08Z ===
Error: setup payload error: malformed BUZZ_ACP_SETUP_PAYLOAD: unknown variant `missing_binary`,
expected one of `normalized_field`, `env_key`, `cli_login`, `cli_config_invalid`, `git_bash`
at line 1 column 171
```
4. `auto_restart_on_config_change` retries and the same line repeats.
Encountered with Buzz Desktop 0.5.3 on macOS 15 (arm64), agent runtime `hermes`, after moving `Buzz.app` into `/Applications` — the harness binary was resolvable from the shell the app had previously been launched from, but not from the GUI `PATH`. The unresolvable-binary detection was correct; only the reporting path was broken.
## Impact
`MissingBinary` is the one requirement a user cannot diagnose from the UI, because the agent never gets far enough to describe itself. It is also the most likely requirement for anyone running a custom or preset-external harness, where GUI-vs-shell `PATH` differences are routine. The failure mode reads as "the agent is broken" rather than "this command isn't on the path".
## Suggested fix
Add the missing variant to `RequirementPayload` so the payload round-trips:
```rust
/// The configured harness command could not be resolved on PATH.
MissingBinary { command: String },
```
plus its `instruction()` arm, so the nudge names the command that could not be found.
Worth considering alongside it: a round-trip test asserting every `Requirement` the desktop serialises deserialises in the harness. The two enums are edited in different crates and nothing currently ties them together — this drifted silently. A tolerant fallback (unknown surfaces degrade to a generic nudge rather than a fatal parse error) would also stop the next added variant from bricking startup the same way.
## Related
Not a duplicate of #2698 (implicit reply delivery) — separate failure path, though both surfaced in the same debugging session. Searched open issues and PRs for `BUZZ_ACP_SETUP_PAYLOAD` and `missing_binary`: no matches.
Contributor guide
Research direction
Start in crates/buzz-acp/src/setup_mode.rs, reading RequirementPayload, SetupPayload::from_raw_env_value, and instruction(); compare them with the MissingBinary serialization in desktop/src-tauri/src/managed_agents/runtime.rs and readiness.rs. Verify that a missing-binary payload parses, names the command in its instruction, and no longer causes the fatal startup error in lib.rs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100