feat(desktop): expose a secured local control API/CLI for Desktop configuration and agent lifecycle

**Motivation**

Buzz has a strong agent-facing relay CLI, but the installed Desktop remains a separate, UI-only control plane for important local state. The `buzz` CLI can operate messages, channels, repositories, workflows, and relay-side agent drafts, but it cannot directly and reliably manage the Desktop instance that owns:

- the authenticated human identity and OS-keyring material;
- the local managed-agent registry;
- ACP runtime/harness registrations and launch arguments;
- exact provider/model/thinking/run-target settings;
- agent start/stop/restart state;
- pending owner-review requests;
- live session/runtime diagnostics and effective tool capabilities.

This becomes a practical blocker when an owner explicitly asks an agent to configure Buzz itself. Today the agent must either hand the work back to the human, edit undocumented local files, or use accessibility/pixel automation against Desktop dialogs. UI automation is fragile, difficult to make idempotent, hard to audit, and risky around one-time identity/private-key screens.

A concrete workflow on Buzz Desktop 0.5.5 required UI automation to register custom ACP runtimes, create managed agents with exact model aliases, add them to a channel, start/stop them, and inspect live runtime state. The relay CLI could handle adjacent channel operations, but not the Desktop-local configuration. A live capability check also caught a runtime whose UI configuration looked restricted while its fresh session actually exposed a broad command catalog; a structured Desktop/runtime inspection surface would make this kind of fail-closed verification much safer.

This is not a request to export the owner's private key or let a remote agent silently impersonate the owner. It is a request for a supported, local, owner-authorized automation boundary.

**Proposed solution**

Expose a versioned local Desktop control API, with a matching CLI namespace such as `buzz desktop ...`. A Unix-domain socket on macOS/Linux and named pipe on Windows would keep this separate from the relay API.

Possible initial surface:

```text
buzz desktop status --json
buzz desktop runtimes list|get|add|update|remove|probe
buzz desktop agents list|get|create-draft|update-draft
buzz desktop agents start|stop|restart
buzz desktop agents runtime|sessions|capabilities
buzz desktop approvals list|show|approve|deny
buzz desktop settings get|set
```

The exact command shape is non-normative. The important properties are:

1. **Desktop remains the authority.** Commands are executed by the running Desktop process using its existing authenticated context and keyring; keys and secrets are never returned to the caller.
2. **Scoped local authorization.** The owner pairs a local automation client once and grants explicit scopes such as `desktop.read`, `agents.configure`, `agents.lifecycle`, or `approvals.request`. Capabilities should be revocable and optionally time-limited.
3. **Owner review for sensitive mutations.** Identity creation/rotation, secret changes, permission expansion, destructive actions, and owner-signed relay mutations should still produce an exact Desktop diff for human approval. Automation can prepare and submit the draft without bypassing consent.
4. **Structured, idempotent operations.** JSON input/output, stable object IDs, dry-run/diff support, idempotency keys, and clear conflict/error states. No success response merely because an ephemeral request was published; report whether Desktop received, queued, applied, or rejected it.
5. **Runtime truth, not only desired config.** Read operations should distinguish configured harness/model/tools from the effective fresh-session values observed over ACP. This is useful for detecting adapters that ignore launch flags or silently expose additional tools.
6. **No undocumented file editing.** The API should reuse Desktop's validation, persistence, restart/session-invalidation, keyring, and runtime-discovery code rather than making callers mutate `managed-agents.json` or custom-runtime files directly.
7. **Safe defaults.** Local clients begin read-only; secret values are redacted; private keys are never printed; destructive or privilege-expanding operations fail closed without an interactive owner grant.

A minimal first increment could be read-only `status`, `runtimes list/get`, `agents list/get/runtime`, and lifecycle `start/stop/restart`, followed by draft-based configuration mutations.

**Alternatives considered**

- **Continue using Desktop accessibility/UI automation:** works for experiments, but is brittle across layout changes, cannot provide reliable idempotency or structured errors, and may traverse sensitive dialogs.
- **Expand only relay-side `buzz agents draft-*`:** useful (#3115), but it cannot inspect or control Desktop-local runtime state, and current ephemeral draft delivery/owner-review behavior has separate reliability gaps (#3791, #3559, #4334).
- **Edit local Desktop state files directly:** bypasses validation/keyring logic, is unsupported, and risks corrupting or desynchronizing runtime state.
- **Use a headless agent-host/spawner instead:** valuable for always-on remote seats, but does not solve automation of the owner's existing Desktop-local agents, settings, and approval surfaces.
- **Expose a general remote HTTP admin API:** broader and riskier than needed. A local IPC boundary with explicit owner-granted scopes is preferable.

**Additional context**

Installed environment used for the concrete workflow:

- Buzz Desktop 0.5.5 (`xyz.block.buzz.app`)
- macOS, Apple Silicon
- bundled/local `buzz` CLI; the current CLI has no `--version` option

Closest related work, but not duplicates:

- #3399 — configurable ACP runtime registry; this request would make that registry scriptably manageable and inspectable.
- #3115 — CLI parity for `--mcp-command` and `--env`; useful for relay-side drafts, but not Desktop-local state, lifecycle, diagnostics, or durable receipt.
- #3791 / #3559 / #4334 — relay-originated agent drafts can be lost, dropped, or not surfaced; a Desktop control endpoint should report durable receipt/queue/application state.
- #2453 — runtime liveness and restart control; this proposal includes a structured local lifecycle surface for that narrower need.
- #2931 — owner-visible capability/readiness manifests; this proposal would expose the same runtime truth through a redacted, scriptable read surface.
- #3590 — CLI management for one Desktop-only preference surface (sidebar categories).
- #3554 / #2859 — machine enrollment and headless multi-agent hosts; complementary, not a replacement for Desktop-local control.
- #3227 — owner-approved app-installed managed-agent bundles.

Duplicate searches performed for `desktop CLI`, `headless`, `local API`, `runtime registry`, `managed agent`, `Desktop automation`, and agent create/start/stop lifecycle. No issue found for a general secured local Desktop control API/CLI.

Start by mapping the existing Desktop configuration, keyring, persistence, runtime-discovery, lifecycle, and approval paths mentioned in the issue, along with the current bundled buzz CLI. Compare those entry points with the proposed read-only status, runtime, agent, and lifecycle surface; done should include an agreed versioned local boundary, scoped authorization, redaction, structured state, and owner review for sensitive changes.

Written by the indexing model from the issue text.