feat(desktop): register Grok Build as native ACP runtime + onboarding harness

[Bartok9]

Summary

Register Grok Build as a first-class ACP harness and show it on Set up your agent harnesses next to Claude Code and Codex.

Closes #2347. Companion: Cursor harness #2536 / #2535.

Why

Grok Build already speaks ACP natively:

grok agent stdio
# managed default:
grok agent --always-approve stdio

Without catalog registration, Desktop cannot discover, install-hint, or process-sweep Grok the way it does other runtimes. Onboarding also hard-filters visible harnesses (ONBOARDING_RUNTIME_ORDER).

What changed

• KNOWN_ACP_RUNTIMES: grok entry (commands: grok, aliases grok-build / grokbuild)
• Default args: agent --always-approve stdio (avoids TTY tool-permission blocks for managed agents)
• PATH discovery includes ~/.grok/bin
• Skills: .grok/skills
• Auth: login_hint for grok login / XAI_API_KEY (no stable auth status probe in current CLI — auth_probe_args: None, same posture class as Goose)
• Onboarding visibility: claude, codex, grok
• agentReadiness treats Grok like other CLI harnesses when available
• Process-sweep binary name grok
• Unit tests + buzz-acp README

Non-claims

• Does not add Cursor (separate PR feat(desktop): register Cursor as native ACP runtime + onboarding harness #2536).
• Does not invent a fake grok auth status probe — CLI currently has grok login / grok auth setup, not a codex-style status subcommand.

Test plan

• cargo test --lib normalizes_grok
• cargo test --lib resolves_grok
• cargo test --lib grok_runtime
• node --test onboardingRuntimeSelection.test.mjs
• Desktop: harness page shows Grok Install; after install + grok login / XAI_API_KEY, agent spawn uses grok agent --always-approve stdio

Reviewer notes

• --always-approve is intentional for managed agents (Buzz spawns without a TTY). Users who want interactive approval can override agent args.
• Onboarding allowlist remains product-scoped (not goose/buzz-agent).

Signed-off-by: Bartok9 danielrpike9@gmail.com

[Bartok9]

Coordination note with Cursor PR #2536

Grok Build installs both grok and agent PATH shims (~/.grok/bin/agent, often linked as ~/.local/bin/agent).

Cursor’s PR intentionally does not treat basename agent as Cursor — it prefers cursor-agent. Please keep these PRs consistent if either is revised:

• Grok: spawn via grok + args agent --always-approve stdio
• Cursor: spawn via cursor-agent + args acp

[Bartok9]

Polish pass (rebased on upstream/main)

HEAD ea75f3e6 — rebase + maintainer docs/tests.

Differentiation vs Cursor (#2536) and other Grok PRs

• Binary: registry commands: &["grok"] only — ACP via args agent --always-approve stdio.
• Never claims bare PATH shim agent (that disambiguation stays on Cursor’s own entry).
• Onboarding: ONBOARDING_RUNTIME_ORDER includes grok.
• Docs/tests: discovery comment + README maintainer note + grok_does_not_claim_bare_agent_path_shim unit test.

Test plan

• Discovery unit tests for grok args normalization + bare-agent non-claim (run in CI with desktop mesh-llm as configured by repo).

[tony-freedomology]

Dogfood review (Mac mini, 2026-07-24)

Verified the Grok Build ACP path this PR registers, against a live home Buzz relay + installed Grok CLI.

Environment

• grok --version: 0.2.111 (94172f2aa4e5) [stable]
• Binary on PATH via ~/.local/bin/grok (also present under ~/.grok/bin)
• Host: macOS aarch64

Live ACP handshake

grok agent --always-approve stdio

Sent JSON-RPC initialize over stdio. Agent responded with:

• protocolVersion: 1
• agentCapabilities.loadSession: true
• promptCapabilities.embeddedContext: true
• MCP capabilities advertised
• subsequent _x.ai/* notifications (MCP servers, announcements)

So the entrypoint this PR defaults to (agent --always-approve stdio) is real and works today — not a hypothetical adapter.

Catalog / onboarding

• KNOWN_ACP_RUNTIMES entry for id: "grok" looks correct:
  • commands/aliases: grok / grok-build / grokbuild
  • install hint via official xAI script
  • skills dir .grok/skills
  • config ~/.grok/config.toml
  • no fake auth status probe (matches current CLI; login_hint is the right posture)
• Onboarding unit tests pass:
  • node --test src/features/onboarding/ui/onboardingRuntimeSelection.test.mjs → 4/4 green (Claude/Codex/Grok visible + order)

Why this matters

Without catalog registration, Desktop setup only shows the hardcoded known harnesses. Grok Build is already ACP-native; users currently have to hand-wire BUZZ_ACP_AGENT_COMMAND=grok outside the UI. This PR closes that gap the same way Hermes/Cursor PRs do.

Non-blocking notes

1. Desktop Tauri package tests need binaries/buzz-acp-* present; I couldn't run the full desktop/src-tauri cargo suite without the sidecar build path. The onboarding TS tests and live ACP handshake cover the user-facing risk.
2. Consider a follow-up Doctor check that PATH includes ~/.grok/bin when grok isn't found on the default PATH (install script often lands there).
3. Sibling #2344 appears to overlap — worth closing/superceding one after merge to avoid double-registration thrash.

Approve — happy to see this land so Grok shows on "Set up your agent harnesses" next to Claude Code / Codex.

[tony-freedomology]

Additional home self-host dogfood: confirmed on a private Tailscale Buzz relay (ghcr.io/block/buzz:main). After this lands, Grok Build can be picked as a managed harness without forking Desktop. Related: Hermes harness PRs #2656 / #2633 for the same onboarding surface.

[Bartok9]

Thanks for the live dogfood @tony-freedomology — glad the grok agent --always-approve stdio handshake verified clean against a home relay (0.2.111, macOS aarch64). That's exactly the managed-harness path this PR targets: pick Grok Build without forking Desktop.

Consistency note for the related onboarding PRs (#2536 Cursor, #2656/#2633 Hermes): this entry registers commands: ["grok"] only and deliberately does not claim the bare agent PATH shim, so it won't collide with the other harness entries. Happy to rebase again if any of those land first.