feat(backends): add capability registry

[Q00]

Stack

1/3 Capability registry for backend aliases and surfaces.

Next PRs:

• 2/3 Hermes LLM/interview driver support
• 3/3 Auto driver/brake CLI wiring

Changes

• Adds ouroboros.backends capability registry.
• Refactors runtime/provider/config validation to use the registry as source of truth.
• Keeps Hermes runtime-only in this layer.

Validation

• uv run pytest tests/unit/backends/test_capabilities.py tests/unit/providers/test_factory.py tests/unit/config/test_loader.py tests/unit/cli/test_config.py tests/unit/orchestrator/test_runtime_factory.py -q
• uv run ruff check src/ouroboros/backends src/ouroboros/providers/factory.py src/ouroboros/orchestrator/runtime_factory.py src/ouroboros/config/loader.py src/ouroboros/cli/commands/config.py tests/unit/backends/test_capabilities.py

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: APPROVE

Reviewing commit cb62b23 for PR #670

Review record: ea083c3c-b46d-4f36-b60b-776cfb00c743

Blocking Findings

No in-scope blocking findings remained after policy filtering.

Follow-up Findings

• src/ouroboros/cli/commands/config.py:29 [warning] ouroboros config validate still rejects valid alias-backed runtime configs. _VALID_BACKENDS is built from runtime_backend_choices() without aliases, so values like claude_code, codex_cli, opencode_cli, etc. fail the check at line 443 even though the schema explicitly allows them (config/models.py:342) and the runtime factory now resolves them via resolve_runtime_backend_name(). This leaves users with a false validation failure for configs that the rest of the system accepts.

Non-blocking Suggestions

| 1 | tests/unit/backends/test_capabilities.py:17 | Tests | The new registry tests only exercise the pure helper layer. They do not cover the loader integration that changed in get_llm_backend() for runtime aliases like codex_cli, gemini_cli, and opencode_cli, or the claude_code special-case. Adding a few cases in tests/unit/config/test_loader.py would lock down the user-visible env-var contract. |

Design Notes

Centralizing backend capability metadata is the right direction and removes several duplicated alias maps. The main gap is that validation still uses a canonical-only view, so the new registry contract is not applied consistently across all touched surfaces.

Policy Notes

• No in-scope blocking findings remained after policy filtering; downgraded verdict accordingly.

Recovery Notes

First recoverable review artifact generated from codex analysis log.

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: APPROVE

Reviewing commit ba592f5 for PR #670

Review record: 005bf2fb-1456-4e87-acc1-96858414e129

Blocking Findings

No in-scope blocking findings remained after policy filtering.

Non-blocking Suggestions

None.

Design Notes

The central registry reduces duplicated backend-name logic across config, runtime, and provider factories, and the refactor appears contract-consistent within the changed surface. Added unit coverage is aligned with the main alias/capability paths; I did not execute tests because pytest is not installed in this environment.

Recovery Notes

First recoverable review artifact generated from codex analysis log.

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[shaun0927]

Ready for maintainer review — re-review ping

This PR (capability registry) is now in a clean merge-ready state on commit ba592f5b:

• Bot review: APPROVED on the current head; the only outstanding follow-up was the ouroboros config validate rejecting alias-backed runtime configs (claude_code, codex_cli, opencode_cli, gemini_cli, hermes_cli), which is now fixed via the alias-aware resolve_runtime_backend_name helper plus parametrized regression coverage at tests/unit/cli/test_config.py.
• Mergeable: MERGEABLE/CLEAN against main.
• Verification: UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/unit/cli/test_config.py tests/unit/backends/test_capabilities.py → all passing locally on the head.
• Scope: Centralized backend capability metadata (canonical names + aliases + per-capability flags) and replaced the duplicated alias maps. The new registry is now applied consistently across the runtime factory, schema, and the CLI config validate path.

Why this is safe to merge

1. The capability registry is pure helper code with no behavior change beyond the alias-resolution it enables.
2. The new tests pin down the user-visible env-var contract for both the canonical names and the registered aliases the schema already accepts.
3. There are no remaining bot blocking findings, no outstanding non-blocking suggestions, and no design notes flagging unaddressed risk.

Q00 maintainers — could you take a final pass and merge if it looks good? Happy to rebase if anything stack-related needs aligning post-merge of the foundation chain.

[shaun0927]

Re-review ping

Status

• ouroboros-agent[bot] verdict: APPROVE on the current head ba592f5b.
• CI: 6/6 green (Ruff Lint, Test Python 3.12 / 3.13 / 3.14, MyPy Type Check, Bridge TypeScript).
• mergeable / mergeStateStatus: MERGEABLE / CLEAN.
• This is the bottom of the stack/auto-capabilities/{1,2,3} stack and is the unblocker for feat(providers): support hermes interview driver #671 / feat(auto): wire driver selection through capabilities #672 / fix(auto): align MCP resume bounds #680.

What the PR does

Centralizes backend metadata in a single capability registry (src/ouroboros/backends/capabilities.py) so config validation, runtime selection, and provider factories all consult the same source of truth instead of duplicated alias maps. Every other PR in this stack (#671 Hermes driver promotion, #672 driver/brake selection, #680 MCP resume bounds) reads from this registry; merging this first removes the duplicated alias logic in those changes.

Iterative improvements driven by the bot

The bot's APPROVE on the prior head still flagged one user-visible follow-up: ouroboros config validate rejected valid alias-backed runtime configs (claude_code, codex_cli, opencode_cli, …) because _VALID_BACKENDS was built from the canonical-only runtime_backend_choices() view. The schema (config/models.py:VALID_RUNTIME_BACKENDS) explicitly accepts those aliases and the runtime factory resolves them via resolve_runtime_backend_name(), so config validate was the only surface still on the canonical-only set.

ba592f5b fix(config): accept alias-backed runtime_backend in config validate resolves this:

• The validate path now uses resolve_runtime_backend_name() (alias-aware) instead of a separate set.
• The canonical-only _VALID_BACKENDS is preserved for config backend (the curated public-facing switchable list), so the change is scoped.
• Parametrized regression coverage in tests/unit/cli/test_config.py for claude_code / codex_cli / opencode_cli / gemini_cli / hermes_cli.

Why merging is safe

• The follow-up was the only outstanding finding from the prior review; the new bot review on ba592f5b returned no blocking findings and no non-blocking suggestions.
• All 6 CI jobs are green on the head commit (Python 3.12 / 3.13 / 3.14 + MyPy + Ruff + Bridge TS).
• Change is additive at the registry layer and only relaxes the validate predicate; the canonical-only switchable surface is untouched.
• Reduces duplication that would otherwise need to be re-fixed in each downstream PR in the stack.

cc @Q00 — please consider merging this so the rest of the stack (#671 → #672 → #680) can re-base onto main and land in order.