Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: Control UI/TUI session model switching could pass a provider-qualified display alias like lmstudio-moe/MoE through sessions.patch, which let the provider receive MoE instead of the canonical local model id.
• Why it matters: LM Studio and other local providers reject display aliases as invalid model identifiers, breaking user-selected mid-session model switches.
• What changed: Shared model selection now resolves provider/Alias through the configured alias index when the provider matches the alias target, before existing allowlist/catalog validation and persistence.
• What did NOT change (scope boundary): No fallback behavior, provider-specific LM Studio logic, Telegram behavior, or broad Control UI state handling changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Bug: TUI mid-session model switch passes raw alias instead of resolved model ID #75163
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: resolveModelRefFromString resolved aliases only when the entire raw model string matched a configured alias. Bare MoE resolved, but lmstudio-moe/MoE was parsed as provider lmstudio-moe and model MoE.
• Missing detection / guardrail: Existing tests covered bare aliases and slash-form aliases, but not provider-qualified display aliases emitted by session/model selection paths.
• Contributing context (if known): Control UI/TUI session state can combine a server-reported model alias with its provider into provider/Alias, then send that value through sessions.patch.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
  • Target test or file: src/agents/model-selection.test.ts, src/gateway/sessions- patch.test.ts
  • Scenario the test should lock in: lmstudio-moe/MoE resolves and persists as lmstudio-moe/ qwen3.6-35b-a3b when MoE is configured as that model’s alias.
  • Why this is the smallest reliable guardrail: The resolver test locks the shared canonicalization rule; the Gateway patch test proves the user session persistence boundary stores the canonical override.
  • Existing test that already covers this (if any): Existing tests covered bare aliases and explicit provider/model refs, but not provider-qualified aliases.
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

Users can switch to configured aliased local/provider models from Control UI/TUI without the provider receiving the display alias as the model id.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

  Before:
  [model switch: lmstudio-moe/MoE] -> [sessions.patch stores/parses MoE as model] -> [provider
  rejects invalid model id]

  After:
  [model switch: lmstudio-moe/MoE] -> [shared alias resolver maps to qwen3.6-35b-a3b] ->
  [sessions.patch persists canonical override]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local dev environment
• Runtime/container: Node/pnpm workspace
• Model/provider: LM Studio-style local provider alias (lmstudio-moe/MoE) covered by regression tests
• Integration/channel (if any): Control UI/TUI session model switching via sessions.patch
• Relevant config (redacted): agents.defaults.models["lmstudio-moe/qwen3.6-35b-a3b"].alias = "MoE"

Steps

1. Configure an allowed model with alias MoE for canonical ref lmstudio-moe/qwen3.6-35b-a3b.
2. Send sessions.patch with model lmstudio-moe/MoE.
3. Inspect the persisted session override.

Expected

• Session override persists provider lmstudio-moe and model qwen3.6-35b-a3b.

Actual

• Before this PR, lmstudio-moe/MoE was treated as direct model MoE, causing an invalid model identifier path.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test src/agents/model-selection.test.ts
  • pnpm test src/gateway/sessions-patch.test.ts
  • pnpm test src/agents/model-selection.test.ts src/gateway/sessions-patch.test.ts ui/src/ui/
    chat-model-ref.test.ts ui/src/ui/chat-model-select-state.test.ts ui/src/ui/views/
    chat.test.ts
  • pnpm exec oxfmt --check --threads=1 src/agents/model-selection-shared.ts src/agents/model-selection.test.ts src/gateway/sessions-patch.test.ts ui/src/ui/chat-model-ref.ts ui/src/ui/chat-model-ref.test.ts ui/src/ui/chat-model-select-state.test.ts
  • pnpm build
  • git diff --check
  • pnpm dlx codex review --base origin/main
• Edge cases checked: Existing slash-form alias coverage still passes; explicit allowlisted provider/model refs still pass; provider-qualified alias only resolves when the provider matches the alias target.
• What you did not verify: Live LM Studio server behavior; Testbox pnpm check:changed was blocked because Blacksmith CLI was not authenticated and no BLACKSMITH_ORG was configured.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: A provider/Alias string could be mistaken for a real provider/model ref.
  • Mitigation: The new resolution only applies when the suffix matches a configured alias and the prefix provider matches the alias target provider; otherwise existing parsing and allowlist validation are preserved.

Built with Codex