Summary

Adds hermes migrate xai [--apply] [--no-backup] — a one-shot, opt-in CLI helper to rewrite config.yaml so it stops referencing xAI models being retired on May 15, 2026. Pairs with #23278 (doctor + chat-startup warning) — that PR tells users what needs to change; this PR is the actual fix-it button.

Stacked on top of #23278

This PR's branch contains the 3 commits from #23278 plus 2 new commits:

3dd1d620a feat(cli): hermes migrate xai [--apply] [--no-backup]                  ← new
9322cf948 feat(xai): apply_migration — rewrite config.yaml in-place via ruamel    ← new
2e6bf2177 feat(cli): warn about retired xAI models at chat startup                ← from #23278
0f776094a feat(doctor): surface xAI model retirement in hermes doctor             ← from #23278
bf9a09abf feat(xai): detect retired xAI models (May 15, 2026)                     ← from #23278

• If feat(xai): detect retired xAI models (May 15, 2026) in doctor + chat startup #23278 merges first → this PR becomes a clean 2-commit follow-up.
• If this PR merges first → feat(xai): detect retired xAI models (May 15, 2026) in doctor + chat startup #23278 becomes empty and I'll close it.

What's new in this PR (the bottom 2 commits)

hermes_cli/xai_retirement.py — apply_migration()

• Reads config.yaml with ruamel.yaml round-trip (YAML(typ="rt"), preserve_quotes=True) so comments, key order, indentation, and scalar types are preserved. Treats config.yaml as a user-edited file, not a data dump.
• For each RetirementIssue returned by find_retired_xai_refs:
  • sets parent[leaf] = issue.replacement
  • if issue.reasoning_effort is non-empty (i.e. the source model was a *-non-reasoning variant), also writes a sibling reasoning_effort key alongside the model — this is the migration nuance that's easy to miss when swapping the model name alone.
• Writes a timestamped backup <config>.bak-pre-migrate-xai-YYYYMMDD-HHMMSS before rewriting; opt-out via backup=False.
• Returns an ApplyResult(file_path, backup_path, issues_resolved, config_changed) so callers can render whatever feedback they want.
• Empty-issues list, missing slot, or empty config → no-op (no backup written, no rewrite).

hermes_cli/migrate.py — CLI handler

New module to keep main.py dispatching only. cmd_migrate_xai:

• Always prints the diagnostic block (same format as hermes doctor's xAI section).
• Default = dry-run: prints what would change, returns 0.
• --apply: backs up + rewrites; prints success summary or surfaces error and returns 1.
• --no-backup: opt-in only.

hermes_cli/main.py — sub-parser wiring

Registers a new top-level migrate parser with a xai sub-parser, modeled on the existing gateway-style nested sub-parsers. Imports the handler module locally (same pattern as cmd_fallback).

End-to-end smoke test

On a config with comments and the four retired-model slots populated:

# Hermes config — manually crafted for migration smoke test
principal:
  provider: xai
  model: grok-4-1-fast-non-reasoning  # this should migrate
  temperature: 0.5
auxiliary:
  vision:
    provider: xai
    model: grok-4-fast      # ambiguous variant
delegation:
  model: grok-code-fast-1   # retiring

hermes migrate xai --apply produces:

# Hermes config — manually crafted for migration smoke test
principal:
  provider: xai
  model: grok-4.3                     # this should migrate
  temperature: 0.5
  reasoning_effort: none
auxiliary:
  vision:
    provider: xai
    model: grok-4.3         # ambiguous variant
delegation:
  model: grok-4.3           # retiring

…with config.yaml.bak-pre-migrate-xai-20260510-210033 next to it. Comments, key order, type literals (the 0.5 float) — all preserved.

Tests

17 new unit tests in tests/hermes_cli/test_migrate_xai.py:

• No-op paths: empty config, empty issues list, missing file → FileNotFoundError, clean config produces config_changed=False and no backup.
• Surgical replacement: principal, auxiliary.vision, delegation, plugins.image_gen.xai. auxiliary.compression (openai, untouched). principal.temperature survives.
• Migration semantics: non-reasoning variant adds reasoning_effort: "none"; ambiguous bare names get the right replacement.
• Round-trip preservation: top-of-file comment, inline comments on unmodified lines, top-level key order.
• Backup behavior: default backup written, filename prefix correct, backup=False skips, no-changes → no backup.
• Idempotence: applying twice is safe — the second pass finds zero issues and does nothing.

50/50 tests pass when combined with the test suite from #23278 (pytest tests/hermes_cli/test_xai_retirement.py tests/hermes_cli/test_migrate_xai.py).

Backward compatibility

• Pure addition. No public API changes, no config schema changes.
• ruamel.yaml is already in pyproject.toml (>=0.18.16,<0.19) — no new dependency.
• The migrate command is opt-in: nothing happens to a user's config unless they explicitly run hermes migrate xai --apply.
• Default backup is on; --no-backup is the only way to skip it.

Why one PR per layer

PR #23278 (diagnostic) and this PR (action) could've been a single 700-LoC PR. Splitting them gives:

• A useful diagnostic available even if review on the rewriter takes longer (the doctor + startup warning ship value on day 1).
• A smaller second PR focused on the one tricky bit: ruamel round-trip semantics. Easier to review the YAML-rewriting logic in isolation.
• Clear answer to "what if the user just wants to know without me touching their config?" — that user runs hermes doctor and stops there.