block / block/buzz

[Bug] Desktop emits a setup payload buzz-acp cannot parse — missing_binary hard-fails the agent into a restart loop

Open Beginner friendly
#4,628 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.