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

[BaneHive]

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:

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:

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:

#[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 <Agent> (<pubkey>) 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:

/// 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.