feat: add explicit headless transport for Grok and OpenCode

[EmersonBraun]

Parent

#37

What to build

Add provider-specific headless transport support for grok-cli and opencode-cli while preserving ACP as the default. The implementation must not assume that the two CLIs have identical flags or output framing.

Acceptance criteria

• --transport acp remains the default for both CLIs.
• --transport headless is explicit and uses a provider-specific command/argument builder.
• --transport auto is accepted only for local runs and tries ACP before headless.
• CI never performs silent ACP-to-headless fallback.
• Headless output is normalized to the same versioned JSON envelope as ACP.
• Provider-specific framing, exit codes, version requirements, and unsupported capabilities are represented in the registry.
• Headless mode receives the same environment, timeout, cancellation, redaction, context, and tool-denial policy as ACP.
• Offline fixtures cover valid output, logs around output, malformed output, timeout, cancellation, and unsupported version.
• Existing Codex and Claude adapters are not changed to use headless behavior accidentally.
• Diagnostics identify provider, transport, version, and reason for any fallback.

Blocked by

• Blocked by feat: support Grok Build CLI through ACP #41 for Grok provider contract.
• Blocked by feat: support OpenCode CLI through ACP #42 for OpenCode provider contract.
• Blocked by feat: harden the bounded local CLI worker #40 for bounded CLI lifecycle.

Files and references

• src/grok-cli-adapter.ts
• src/opencode-cli-adapter.ts
• src/provider-registry.ts
• test/cli-smoke.test.mjs
• Grok headless documentation
• OpenCode CLI documentation
• ADR-0001

Notes

Do not implement a generic arbitrary-command adapter. A provider is supported only when its headless framing is fixture-tested.