Native ZeroClaw ACP runtime with agent alias configuration #4161

Motivation

Buzz Desktop can run ZeroClaw successfully through a custom ACP runtime, but the setup currently requires users to understand implementation details from both products:

• Manually register a custom harness with command zeroclaw and argument acp.
• Configure a persistent ZeroClaw [acp].default_agent because a generic stdio ACP client does not send ZeroClaw's agentAlias extension.
• Put a ZeroClaw agent alias such as fable into model-shaped UI even though the alias selects an agent, not an underlying model.
• Diagnose an invalid session/new request only after the managed agent starts.

This makes an otherwise working integration difficult to discover and easy to misconfigure.

Proposed solution

Add ZeroClaw as a native managed-agent runtime alongside the existing runtime presets.

• Register a preset that launches zeroclaw acp, with the ZeroClaw ACP documentation and supported installation guidance.
• Expose a runtime-specific Agent alias field instead of treating the alias as a provider or model.
• Keep provider, model, tools, and security configuration authoritative in ZeroClaw rather than duplicating those settings in Buzz.
• Pass the selected alias through a process-scoped ZeroClaw selector when available. For older ZeroClaw versions, show an actionable instruction to set the ACP default agent.
• Run an ACP readiness check that covers initialize and session/new, then surface the selected runtime and alias in the managed-agent summary or logs.
• Hide provider/model requirements that do not apply to the ZeroClaw runtime.

The first version can accept a manually entered alias. Optional alias discovery can be added when ZeroClaw exposes a stable machine-readable listing contract.

Alternatives considered

• Keep using a custom harness JSON file. This works, but it leaves discovery, validation, and field semantics to the user.
• Create one custom runtime entry per ZeroClaw agent. This duplicates launcher configuration and still lacks readiness validation.
• Continue overloading the model field with the agent alias. This obscures which product owns model selection and makes runtime self-reporting misleading.
• Require a global ZeroClaw default agent. This prevents independent Buzz runtime entries from selecting different ZeroClaw agents cleanly.

Additional context

The custom integration has been exercised end to end with Buzz Desktop 0.5.3 and ZeroClaw ACP 0.8.3. No existing Buzz issue or pull request matching a native ZeroClaw runtime was found.

PR #3868 is the expected implementation foundation for this issue. Its first-class runtime catalogue, compatibility and authentication probes, readiness handling, and onboarding hooks should be reused rather than creating a parallel ZeroClaw-specific path. ZeroClaw should remain a separate follow-up instead of expanding #3868's OpenClaw scope.

Related but separate work:

• Linked built-in agents discard provider/model edits and return to “needs configuration” #4157 tracks linked built-in agents discarding provider/model edits.
• [Bug] buzz-acp agents go deaf in threads they've joined unless re-mentioned. #2270 and fix(acp): follow threads the agent participates in (#2270) #2375 track participation-based thread following.
• Managed agents: add Hermes, Kimi Coding, OpenCode and OpenClaw runtime adapters #3696 is prior art for adding native managed-agent runtime adapters.

ZeroClaw's current ACP alias-selection contract is documented here:

https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/book/src/channels/acp.md#sessionnew