Rename AGENT_BACKEND to DEFAULT_BACKEND

[dcellison]

Summary

Renames the installation-wide and per-user "which backend by default" knob from AGENT_BACKEND to DEFAULT_BACKEND, paralleling DEFAULT_MODEL and dropping the redundant "agent_" prefix (backends are the agents in this codebase). The old name is still read for one release with a one-shot deprecation warning at every reader; all writers emit the new name only.

This is groundwork ahead of adding the Pi backend (#696), so that work only learns the new vocabulary.

What changed

• Config.agent_backend → Config.default_backend and UserConfig.agent_backend → UserConfig.default_backend. Every constructor call and attribute access swept.
• Env var / config key: AGENT_BACKEND → DEFAULT_BACKEND (env), agent_backend: → default_backend: (users.yaml per-user key), AGENT_BACKEND → DEFAULT_BACKEND (install.conf env dict).
• Shared resolver _resolve_default_backend(get, new_key, old_key, *, context, default) in config.py: reads the new key, falls back to the old with a one-shot per-context deprecation log. Takes a required default so the two absence semantics stay distinct — global readers pass default="claude" (installation default); the per-user users.yaml reader passes default=None so a backend-less user still inherits the global backend via the existing user_backend or global_backend cascade (rather than being pinned to claude on a non-claude install).
• Five readers routed through the resolver: load_config (env), _cmd_apply (install.conf dict), behavioral._run_cli (env), _load_user_configs (per-user yaml), plus the wizard prefill.
• Installer (_cmd_apply) consumes the install.conf env dict directly (never through load_config), so it migrates a legacy AGENT_BACKEND key to DEFAULT_BACKEND once at the top of apply, before any backend gate reads it or /etc/kai/env is written. Without this, a legacy install.conf would validate a codex/goose default model against the wrong (claude/anthropic) surface and fail, or silently skip backend-specific setup.
• Four installer-side users.yaml scanners (_users_yaml_goose_providers, _users_yaml_agent_backends, _collect_backends_from_yaml, _collect_goose_os_users_from_yaml) read each entry's backend through a new _entry_backend(entry) helper (prefer default_backend, fall back agent_backend).
• Wizard: prompt label "Agent backend" → "Default backend"; prefill reads either key; writes DEFAULT_BACKEND only (so a re-run silently migrates install.conf).
• Templates (templates/.env, templates/users.yaml, templates/config/goose-config.yaml) and docs (README; wiki pages pushed after merge).

Internal function parameters named agent_backend that hold the effective (post-cascade) backend at a call site (e.g. models_for_backend, review_pr, run_triage, _apply_goose_config) are intentionally left unchanged — they name a runtime value, not a default.

Test plan

• make check (ruff + format) clean
• make test clean (4576 passed, 1 skipped; +18 over main)
• New back-compat tests: legacy AGENT_BACKEND env still resolves with a warning; new key wins when both set; legacy agent_backend: users.yaml key still resolves with a warning
• New inheritance regression guard: a users.yaml user omitting the backend key inherits a non-claude global backend (resolver default=None), not claude
• New apply-path tests: a legacy AGENT_BACKEND=codex install.conf validates against the codex surface and writes /etc/kai/env with DEFAULT_BACKEND and no AGENT_BACKEND; a new-name install.conf passes through cleanly
• New scanner coverage: all four installer users.yaml scanners read both key names
• New behavioral-eval coverage: resolves both DEFAULT_BACKEND and legacy AGENT_BACKEND
• New wizard resave-migration test: re-running against a legacy install.conf writes DEFAULT_BACKEND, drops AGENT_BACKEND
• Manual post-merge: make config shows the "Default backend" prompt; a legacy /etc/kai/env with AGENT_BACKEND logs the deprecation warning at startup and still resolves