Bug Report: managed-agents.json corruption, duplicate entries, and empty model dropdown when using custom ACP harnesses

[Jross1719]

Bug Report: managed-agents.json corruption, duplicate entries, and empty model dropdown when using custom ACP harnesses

Environment

• OS: macOS 15.x (Apple Silicon, M3 Pro / M5 Pro)
• Buzz Desktop: latest (build from xyz.block.buzz.app)
• ACP harness: custom SSH wrapper pointing to acp-claude-code (v0.8.0) on remote VPS
• ACP library: @zed-industries/agent-client-protocol@0.1.2

Issue 1: managed-agents.json gets corrupted when changing a harness

Steps to reproduce:

1. Open Buzz Desktop
2. Go to an agent's settings → change its harness (e.g., from buzz-acp to acp-claude-wrapper)
3. Close and reopen Buzz

Expected: Only the selected agent's acp_command field changes. All other agents and entries remain intact.

Actual: Buzz overwrites the entire managed-agents.json file. In practice, this causes:

• Duplicate entries — every harness change adds a new entry for the same agent without removing the old one. After a few changes, each agent appears twice (or more) in the JSON array.
• Lost entries — if the file is rewritten with incomplete data, agents vanish entirely. Buzz then dumps the file to managed-agents.json.invalid and all agents disappear.

Evidence: The file at ~/Library/Application Support/xyz.block.buzz.app/agents/managed-agents.json accumulates duplicate entries. After switching harnesses on 4 agents, the file contained 32 entries for 16 unique agents. Each duplicate had a different slug UUID but the same display_name, causingBuzz to either pick the wrong one or reject the config.

Root cause (likely): Buzz's harness-switch handler rewrites the entire agent store on every change. It does not deduplicate by display_name or slug, and it does not validate that all existing entries are preserved. The write is also not atomic — if interrupted, the file can be truncated to 0 bytes.

Workaround attempted: Locking the file with chflags uchg prevents Buzz from overwriting it, but then Buzz can't write its own runtime state (PID tracking, last-started timestamps), which causes agents to fail to spawn with commit managed-agents.json: Operation not permitted (os error 1).

---

Issue 2: Empty model dropdown when using a custom ACP harness

Steps to reproduce:

1. Set an agent's harness to a custom ACP bridge (e.g., acp-claude-wrapper → acp-claude-code on VPS)
2. Open the agent's settings in Buzz Desktop
3. Click the model dropdown

Expected: The dropdown shows available models from the ACP bridge (e.g., Claude models via OpenRouter or Anthropic).

Actual: The dropdown is empty. No models are listed.

Root cause: The ACP library (@zed-industries/agent-client-protocol@0.1.2) has a hardcoded switch statement in AgentSideConnection that only recognizes 6 methods: initialize, session/new, session/load, authenticate, session/prompt, session/cancel. Any other method (including claude/listModels or /models) hits default: throw RequestError.methodNotFound(method).

The compiled code at node_modules/@zed-industries/agent-client-protocol/dist/acp.js lines 57-60:

case schema.AGENT_METHODS.session_cancel: {
    const validatedParams = schema.cancelNotificationSchema.parse(params);
    return agent.cancel(validatedParams);
}
default:
    throw RequestError.methodNotFound(method);


There is no mechanism for agents to advertise or expose available models. The protocol schema (`schema.json`) has no `listModels` or `models` method defined. This is a protocol-level gap — the ACP spec doesn't define a model-listing endpoint, so no ACP agent can expose models to the client.

**Impact:** Any custom ACP harness (Claude Code, Codex, custom LLM bridges) cannot show models in Buzz Desktop. Users are forced to either:
- Use Buzz's built-in harnesses (which have their own model lists hardcoded)
- Manually configure model IDs in agent settings (if the field exists)

---

## Issue 3: Agents spawn and immediately die (~5 seconds) when using a custom ACP harness

**Steps to reproduce:**
1. Set an agent's harness to a custom ACP bridge
2. Click "Spawn" or send a message to the agent in Buzz Desktop
3. Watch the agent status

**Expected:** Agent spawns, connects to the ACP bridge, and stays alive until the conversation ends or is manually stopped.

**Actual:** Agent spawns, establishes the initial ACP handshake (initialize succeeds), then dies within ~5 seconds. The agent shows as "connected" briefly, then disappears from the sidebar.

**Evidence from logs** (`~/Library/Application Support/xyz.block.buzz.app/agents/logs/`):
- The `buzz-acp` process logs show `buzz-acp starting: ... agent_cmd=<wrapper_path> ...` then `connected to relay` then `presence set to online`
- After ~5 seconds, the agent process exits without any error message in the logs
- No `buzz-acp stopped` log line — the process is killed externally (by Buzz) after the ACP handshake fails on a subsequent request

**Root cause (likely):** After the `initialize` call succeeds, Buzz Desktop sends a follow-up request (possibly `claude/listModels`, `session/new`, or a heartbeat) that the ACP bridge doesn't handle. The bridge either:
- Returns `Method not found` (because the ACP library rejects unknown methods)
- Crashes because the request payload doesn't match expected schema
- Times out waiting for a response that never comes

Buzz interprets this as a connection failure and kills the agent process.

**Note:** This is partially caused by Issue 2 (no model listing) — if Buzz can't get the model list, it may send an invalid follow-up request that the bridge can't handle.

---

## Issue 4: managed-agents.json is not written atomically

**Steps to reproduce:**
1. Modify `managed-agents.json` while Buzz is running
2. Check the file size and content

**Expected:** Writes are atomic (write to temp file, then rename). No partial writes.

**Actual:** Buzz writes directly to the file. If the write is interrupted (crash, signal, disk full), the file is left in a partial state. In practice, the file has been observed truncated to 0 bytes after a harness switch, causing all agents to vanish.

**Evidence:** Backup files exist at:
- `managed-agents.json.bak` (32 entries, from before the corruption)
- `managed-agents.json.bak.0` through `.bak.2` (previous backups)
- `managed-agents.json.invalid` (Buzz's rejection of a bad config)
- `managed-agents.json.json` (another backup variant)

The presence of multiple backup variants suggests Buzz is trying to recover from write failures but the recovery mechanism is incomplete.

---

## Summary of Required Fixes

| Priority | Issue | Fix |
|----------|-------|-----|
| P0 | managed-agents.json corruption on harness change | Write atomically (temp file + rename). Deduplicate entries by `display_name`. Preserve existing entries on rewrite. Validate all entries have required fields (`relay_url`, `acp_command`, etc.) before writing. |
| P0 | Empty model dropdown | Add a protocol-level model listing mechanism. Either: (a) define a `listModels` method in the ACP schema, or (b) have Buzz query the agent's advertised capabilities and fall back to a configurable model list. |
| P1 | Agents die after ~5 seconds | Improve error handling in the ACP connection lifecycle. When a follow-up request fails, log the error and retry instead of killing the agent. Add a minimum connection timeout before declaring the agent dead. |
| P1 | File locking conflict | Remove the `uchg` lock workaround. Instead, use proper file locking (flock) or atomic writes so Buzz can manage its own state without external interference. |
| P2 | Duplicate entries accumulate | Add a deduplication step on config load. If duplicate `display_name` entries exist, keep the one with the most complete data (most fields populated) and remove the rest. |

---

## Additional Context

- The ACP protocol is designed for code editors (VS Code, JetBrains, Zed) connecting to coding agents. Buzz Desktop is using it as a general-purpose agent harness, which exposes gaps in the protocol (no model listing, no heartbeat, no graceful degradation on connection loss).
- The `@zed-industries/agent-client-protocol` package is deprecated (renamed to `@agentclientprotocol/sdk` v0.4.5). The current version (0.1.2) has known limitations that haven't been addressed.
- Users with custom ACP harnesses (especially Claude Code via subscription credits) are effectively locked out of model selection and reliable agent spawning. This is a significant usability barrier for the intended use case.

---

## Workarounds (for reference)

1. **Don't change harnesses after initial setup** — once configured, avoid UI harness switches to prevent config corruption.
2. **Use Telegram instead of Buzz when Mac is closed** — the VPS Telegram gateway runs independently and doesn't require the Mac to be awake.
3. **Manually fix managed-agents.json** — if it gets corrupted, restore from `managed-agents.json.bak` and re-apply harness mappings. (We have a Python script for this: `python3 /tmp/fix_sobel.py`.)

---

Paste that into the Buzz Desktop GitHub repo issues page. The repo URL is `https://github.com/block/buzz` — verify and adjust if it's different.

[washingtonmelissa9138]

依赖版本锁定策略是怎么考虑的 ✨🧪