buzz-acp: BUZZ_ACP_NO_MENTION_FILTER=1 kills the agent at startup, and Desktop shows only "exit code: 2"

[Voisens]

Describe the bug

BUZZ_ACP_NO_MENTION_FILTER is a bare boolean flag whose value parser accepts only the literal strings true and false. Setting it to 1 — the spelling most tools accept for a boolean env var — makes buzz-acp abort during argument parsing with exit code 2, so the managed agent never starts. It never reaches the relay, never subscribes, and never posts.

Two things make this much worse than a normal invalid-config error:

1. The actual error is invisible in Buzz Desktop. The agent's last_error in managed-agents.json is only harness exited with status exit code: 2. The line that names the offending variable is written to the per-agent log file and nowhere else. A user who sets this from the Desktop UI gets a dead agent and a bare exit code.
2. The flag is a footgun by design. 1/0/yes/no/on/off are the conventional spellings for boolean environment variables. Rejecting them outright — rather than accepting them, or rejecting them where the user can see it — turns a typo-class mistake into a fully offline agent.

In my case the agent stayed down for roughly 16 hours before anyone thought to look in the log file.

Steps to reproduce

1. In Buzz Desktop, open a managed agent's settings and add the environment variable BUZZ_ACP_NO_MENTION_FILTER with value 1.
2. Start (or restart) the agent.
3. The agent immediately goes offline. Desktop reports only an exit code.
4. Open %APPDATA%/xyz.block.buzz.app/agents/logs/<pubkey>__<host>.log to find the real cause.

Expected behavior

Either of these would have prevented the outage; ideally both:

• Accept conventional boolean spellings. clap ships BoolishValueParser for exactly this, which accepts true/false, 1/0, yes/no, on/off. This looks like a one-line change per flag.
• Surface the harness's stderr in Desktop. When buzz-acp exits non-zero during startup, the captured stderr — not just the numeric exit code — should reach last_error and the Desktop UI. A clap usage error is a single, already-user-readable line.

Version and platform

• Buzz version: 0.5.4 (Buzz Desktop, buzz-desktop.exe ProductVersion 0.5.4)
• OS: Windows 10 Home 19045 (x64)
• Runtime: managed Claude Code agent, @agentclientprotocol/claude-agent-acp 0.63.0, Claude subscription auth
• Relay: self-hosted community relay

Logs / additional context

From the per-agent log, three consecutive start attempts:

=== stopped Fizz (83a540fe...) at 2026-08-04T20:28:41.396018700+00:00 ===

=== starting Fizz (83a540fe...) at 2026-08-04T20:28:41.459448200+00:00 ===
error: invalid value '1' for '--no-mention-filter'
  [possible values: true, false]

For more information, try '--help'.

=== starting Fizz (83a540fe...) at 2026-08-05T11:59:43.972086500+00:00 ===
error: invalid value '1' for '--no-mention-filter'
  [possible values: true, false]

For more information, try '--help'.

The corresponding record in managed-agents.json — this is everything the UI has to work with:

"last_error": "harness exited with status exit code: 2",
"last_exit_code": 2,
"last_error_code": null

Changing the value to true is the workaround; deleting the variable also restores the agent.

Scope

I verified the rejection only for --no-mention-filter, from the log above. buzz-acp --help shows a family of sibling flags with the same bare-boolean-plus-env shape — --no-ignore-self (BUZZ_ACP_NO_IGNORE_SELF), --no-presence (BUZZ_ACP_NO_PRESENCE), --no-typing (BUZZ_ACP_NO_TYPING), --no-memory (BUZZ_ACP_NO_MEMORY), --no-base-prompt (BUZZ_ACP_NO_BASE_PROMPT) — which are likely affected identically, but I did not test them and am not claiming they are.

Related, though distinct: #4228 also concerns no_mention_filter being hard to confirm from the journal. That one is about the flag's state being unobservable when it works; this one is about the failure being unobservable when it doesn't.