fix(acp): accept missing_binary and unknown setup surfaces

[sniperguard]

Summary

buzz-desktop emits a missing_binary setup requirement when a managed agent's configured harness command can't be resolved in PATH (desktop/src-tauri/src/managed_agents/runtime.rs). buzz-acp's RequirementPayload has no matching variant, so SetupPayload::from_env() fails with a serde error and the harness exits 1 before it can nudge — the agent crash-loops at startup and never comes online. The user sees an agent that is simply dead, with no in-app explanation.

Two changes:

1. MissingBinary { command } + an instruction() arm, so the surface deserializes and produces a nudge.
2. #[serde(other)] Unknown, so any surface this build doesn't recognise degrades to a generic nudge instead of aborting the harness.

(2) is why the failure mode was a crash-loop rather than merely a bad nudge: today an unrecognised surface is fatal. Desktop and buzz-acp ship in one bundle but are versioned independently during development, so the skew is reachable again the next time a surface is added desktop-side.

Related issue

Searched first, per CONTRIBUTING:

• fix(acp): accept missing_binary setup requirement in buzz-acp #3993 fix(acp): accept missing_binary setup requirement in buzz-acp — already fixes (1), mergeable, green CI, reviewed.
• fix(acp): handle missing custom harness binaries #3598 fix(acp): handle missing custom harness binaries — also fixes (1).
• Buzz Desktop 0.5.2: agent_args reset to [] and missing_binary setup payload error prevents OpenCode ACP integration #3824 — same payload error hit through an OpenCode harness.

So (1) here is a duplicate and I'd expect to defer to #3993. (2) is the part neither PR has. If #3993 lands first, I'm happy to rebase this down to just the #[serde(other)] fallback, or split it out as a standalone PR now — whichever you prefer. Flagging rather than opening a competing fix quietly.

One deliberate difference worth a reviewer's eye: #3993 and #3598 both fold MissingBinary into the all_external / any_external groupings in nudge_body(), matching the doc comment in readiness.rs ("No in-app action can fix this — the user must install the binary or update their PATH"). This PR keeps it Buzz-managed and points at Edit Agent → Command instead, because in the case that surfaced this the binary was installed and just wasn't on the GUI app's PATH — an absolute path in Edit Agent fixed it with nothing installed. Both readings are defensible; theirs matches the stated intent, this one matches what actually resolved it. Say which you want and I'll match it.

Testing

cargo test -p buzz-acp --lib setup_mode → 24 passed, 0 failed. cargo clippy -p buzz-acp --all-targets and cargo fmt --check clean.

Two regression tests added:

• setup_payload_deserializes_missing_binary_requirement — the exact payload the desktop emits parses, and the instruction names the command.
• setup_payload_tolerates_unknown_surface — an unknown surface parses to Unknown instead of erroring. Fails without the #[serde(other)].

Also verified against a release build on the real payload that caused the crash-loop (Buzz Desktop 0.5.3, macOS arm64):

• shipped buzz-acp → unknown variant \missing_binary``, exit 1
• patched buzz-acp → entering setup-listener mode, entering setup mode agent=… requirements=1

Repro: give a managed agent a bare binary name that isn't on the GUI app's PATH. The agent log shows the serde error and exit code 1, retried twice ~185 ms apart. No UI change.

🤖 Generated with Claude Code