buzz-acp: BUZZ_ACP_NO_MENTION_FILTER=1 kills the agent at startup, and Desktop shows only "exit code: 2"
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**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/__.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:
```json
"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.
Contributor guide
Assessment
This issue has not been assessed yet.