#1240: Clarify and harden Provider/Model source-of-truth across WebUI, CLI, and Gateway

Summary

Provider/model management currently feels confusing because the WebUI exposes several model-related controls without making their scope and source of truth clear.

This is not one dropdown bug. It is a broader source-of-truth / UX governance problem across:

• Hermes Agent global config
• Hermes CLI session-local and global model switching
• Hermes Gateway/runtime provider resolution
• Hermes WebUI composer model picker
• WebUI Settings default model
• provider authentication and model catalog discovery
• cache/localStorage/session model state
• runtime fallback behavior

The user-facing problem is simple: users need to know which provider/model will handle the next message, why that model was selected, and whether changing a model in one place affects only the current conversation or the global default.

Current confusion points

1. Composer model vs Settings default model

The WebUI does not clearly explain the difference between:

• selecting a model in the conversation composer
• selecting the default model in Settings / Preferences

Expected user mental model:

• Composer model = model for this conversation / next message
• Default model = model used for new conversations
• Existing conversations may keep their own stored model override

The UI should make this scope explicit instead of forcing users to infer it.

2. WebUI model/provider catalog can drift from Hermes CLI

The WebUI still has provider/model catalog logic that can diverge from Hermes Agent / Hermes CLI behavior.

If a provider works in CLI but is missing from the WebUI picker, the user experiences this as WebUI being out of sync with Hermes itself.

3. Runtime fallback behavior is not visible enough

When the primary provider/model fails or degrades, users do not have a clear indication of whether Hermes:

• failed outright
• retried
• used a fallback provider
• used a different model/provider than the one selected in the UI

If fallback happens, the WebUI should make that visible enough for users to trust what happened.

4. Multi-client state can diverge

Hermes Agent, Hermes CLI, Hermes Gateway, and Hermes WebUI may all have different runtime state depending on when each process started and whether a model change was session-local or global.

Examples of state layers that can disagree:

• ~/.hermes/config.yaml global default
• current CLI session model
• current WebUI session model
• Gateway/runtime provider resolution
• WebUI model cache
• browser localStorage
• old session JSON model values
• environment variable overrides

The WebUI should expose enough diagnostics or UI hints to explain which layer is currently winning.

Already-covered adjacent work

This umbrella should not duplicate these active issues/PRs:

• #1228 / #1231: duplicate model IDs across provider groups lose provider identity in the picker.
• #1236: Hermes Agent-supported providers can be invisible in WebUI when absent from WebUI's hardcoded model catalog.
• #1212 / #1221: OAuth providers can show as unconfigured in Settings; active profile provider visibility.
• #732: LLM Gateway active provider and failover visibility.
• #1239: /api/models disk cache should preserve active_provider and default_model metadata.
• #1213 / #1220: concrete provider/model list maintenance PRs.

Those are concrete slices. This issue is meant to organize the remaining source-of-truth and user-mental-model problem.

Suggested implementation slices

This should not be solved in one PR.

PR 1: Clarify model scope in UI copy

Make the visible model controls explain their scope:

• Composer: "Model for this conversation"
• Settings: "Default model for new conversations"
• Existing sessions: indicate when the conversation is using a session-specific model override

This is the smallest user-facing improvement and should not require runtime changes.

PR 2: Add model source diagnostics

Expose enough state for debugging:

• effective current conversation model
• source of that model: session override, default config, localStorage, env, etc.
• active provider
• default model from Hermes config
• whether WebUI is using cached/static/live model catalog data

This can start as API/debug metadata before becoming full visible UI.

PR 3: Align WebUI model catalog with Hermes Agent source of truth

After #1236's narrow provider fix lands or its direction is settled, make WebUI rely more directly on Hermes Agent / Hermes CLI model discovery instead of maintaining a drift-prone hardcoded catalog as the primary path.

Static WebUI provider lists should become fallback, not the main source of truth.

PR 4: Surface runtime/fallback provider state

Reference #732 rather than replacing it.

At minimum, users should be able to see when the actual runtime provider/model differs from the selected provider/model because of fallback, gateway routing, or provider recovery.

Why this belongs in Core Quality and Parity

Model selection is a core Hermes workflow, not an advanced dashboard feature.

If the UI cannot clearly answer "which model will handle my next message?" then provider setup, default model settings, session continuation, and CLI parity all become hard to trust.

This issue is intended to keep future provider/model fixes aligned, avoid duplicate PRs, and make sure small fixes add up to a coherent model-management experience.