feat(agent-runtime): consume ModelRef + Phase 3/5/6/7 prep infra

[claudiusthebot]

What

Single-PR home for the architecture-unification plan, growing as
each phase lands. Currently contains Phases 2.2, 2.3, and additive
prep infrastructure for Phases 3, 5, 6, 7.

Builds on #253 (Phase 1) and #254 (Phase 2.1), both merged.

Phases landed in this PR

Phase 2.2 — /status consumes ModelRef

Telegram + Discord /status read context window + display name
from one ModelRef instead of resolveActiveModelForChat +
getModelInfo back-to-back.

Phase 2.3 — /model consumes ModelRef + modelId fallback

Both /model view builders consume ref.displayName directly.
Resolver shape extended:

interface ActiveModelRefResolution {
  ref: ModelRef | null;
  modelId: string | null;   // ← raw string from the 5-step chain
  source: ActiveModelSource;
}

modelId lets callers display the legacy id when ref is null
(BackendId drift / pre-bootstrap path).

Phase 3 prep — Backend registry shim (agent-runtime/registry.ts)

Adapts the existing legacy BackendFactory registry into Backend
composed objects via adaptQueryBackend.

• getAdaptedBackends(config, ctx, opts?) — init every factory,
  return Backend[].
• adaptOneBackend(id, ...) — init one by id, return Backend | null.
• adaptInstantiatedBackend(instance, ...) — wrap an existing
  BackendInstance without re-init.

Factories whose id is not in BACKEND_IDS are skipped with a
console warning — the typed BackendId union is the source of
truth.

Phase 5 prep — ToolRegistry (agent-runtime/tool-registry.ts)

Canonical store of ToolDescriptors.

• register / registerAll (atomic rollback on collision)
• forPolicy(policy) → ToolDescriptor[] filtered by
  RunPolicy.tools.filter
• parseMcpToolId / groupToolsByServer helpers

Phase 5.x backend renderers (Codex TOML, Claude SDK MCP config,
etc) will consume this.

Phase 6 prep — JsonStore<T> (agent-runtime/store.ts)

Unified persistence primitive for the six existing JSON-backed
stores under src/storage/.

• load → envelope or bare data; .bak fallback on corrupt
• save → write-file-atomic envelope { schemaVersion, savedAt, data }
• migrate hook on version mismatch (returns { value, schemaVersion } | null)
• validate hook (throw to reject malformed)
• Test-friendly: JsonStoreFs + now() injection — no real disk
  I/O in tests.

Per the plan's migration order, first consumer is Codex OAuth
incompat learning (small, low-risk); chat-settings stays last
because it's operationally sensitive.

Phase 7 prep — Backend contract assertions (agent-runtime/contract-tests.ts)

Every concrete backend (Claude SDK, Codex, Kilo, OpenCode, OpenAI
Agents) must pass these:

• assertBackendIdentity — id + label sanity
• assertChatBackendEmitsRunStarted — first event is run_started
• assertChatBackendTerminates — terminates on completed / error
• assertChatBackendEmitsSingleUsage — exactly one usage event on success
• assertCompletedUsageMatchesUsageEvent — completed.result.usage agrees with usage event
• assertBackgroundRunnerLifecycle — started + completed/error
• assertModelCatalogDefaultShape — ref.backend matches identity
• assertUsageTelemetryShape — finite, non-negative counters
• assertBackendContract — runs the full suite, returns the list of checks performed

The assertions throw descriptive ContractViolation errors. Per-
backend test files in Phase 7.x will import these and apply them.

Plan-named Phase 2 targets

Plan said "convert /model, /status, chat query, heartbeat, and
dream to use it."

• /status — done (Telegram + Discord)
• /model — done (main menu + browse view)
• chat query — deferred to Phase 3. Threads ModelRef through
  the dispatcher's runChatTurn interface (replacing legacy
  QueryParams).
• heartbeat / dream — deferred to Phase 4. They currently read
  configRef.heartbeatModel ?? configRef.model ?? getDefaultModel()
  directly (not via the 5-step chain). They'll migrate to ref when
  Phase 4 moves their log-rendering through the new event stream.

What stays the same

• All 16 remaining resolveActiveModelForChat call sites in
  commands.ts / callbacks.ts / reasoning-levels.ts /
  bootstrap.ts keep using the string resolver. They only need
  the raw id — ref adds no value.
• The richer core/errors.ts classifier is still upstream; the
  adapter (Phase 1) ships a small inline one.
• Cache display still reads be.cacheMetrics directly in
  /status. The ref's cacheSupport carries the same value
  (propagated from cacheMetrics) so either works; keeping the
  existing call site keeps the diff minimal.

Tests

Module	Cases
agent-runtime-resolver (Phase 2.1+2.3)	17
agent-runtime-types (Phase 1)	32
agent-runtime-adapter (Phase 1)	18
agent-runtime-tool-registry (Phase 5 prep)	15
agent-runtime-store (Phase 6 prep)	17
agent-runtime-contracts (Phase 7 prep)	21
agent-runtime-registry (Phase 3 prep)	15

• Full suite 2976 / 2988 (12 pre-existing skips). 59 net
  new tests on top of the Phase 1 + 2.1 + 2.2/2.3 cases.
• Type check passes (npm run typecheck)
• No new lint warnings (npm run lint — 18 pre-existing).
• Prettier clean.

Out of scope (deferred — each gets its own PR)

• Phase 3.x: backend handlers emit AgentEvents natively.
  Each backend handler is ~500-1500 LOC of careful surgical work.
  Order per the plan: Codex → Claude SDK → OpenAI Agents → Kilo /
  OpenCode.
• Phase 4: heartbeat / dream log rendering moves to core,
  consuming the event stream.
• Phase 5.x: per-backend ToolRegistry renderer (Codex TOML,
  Claude MCP, etc).
• Phase 6.x: migrate the six existing JSON stores onto
  JsonStore<T>. Order: Codex OAuth incompat → media index →
  cron → triggers → sessions → chat settings.
• Phase 7.x: contract assertions wired into per-backend test
  files (which requires Phase 3.x to populate the event shape).

The plan's own "Do not rewrite every backend at once" guidance is
the reason these are split — each backend rewrite is the kind of
change that warrants its own behavioural-equivalence audit and
test coverage.

Refs docs/talon-architecture-unification-plan.md