feat(desktop): edit delegation models and fallback policy

[andrexibiza]

What does this PR do?

Rebuilds #105250 directly on current main (267a6b79c8e0d8e0456d27948a80b79fea8f63d2) as the Desktop projection of the delegation runtime contract merged in #105347.

This carrier retains the unique Desktop Models/profile editor and its authoritative persistence semantics:

• profile-scoped delegation provider/model selection, including model-only overrides
• ordered delegation fallback policies: default, explicit parent inheritance, none, or a declared chain
• local atomic drafts with incomplete selections blocked from saving
• same-owner catalog, capability, config read, save, and exact read-back across {connectionId, profile}
• stale external-change refusal, failed-save retry, and stale completion rejection after profile/gateway changes
• direct-endpoint metadata preservation until the provider is deliberately replaced
• capability negotiation so older backends do not accept inert fallback controls

It deliberately removes the duplicate runtime fallback implementation from the old branch. Runtime fallback ownership remains in current main via merged #105347. This PR changes neither the primary conversation model nor the top-level fallback chain.

Related issues

• Refs [Feature]: Delegation model has no fallbacks #94629 (the open feature this Desktop editor surfaces)
• Runtime defect delegation.fallback_providers is ignored; delegated workers inherit the parent fallback chain #65038 was settled by merged fix(delegation): pinned children stop inheriting the parent fallback chain; delegation.fallback_providers declares their own (#80450, #65038, salvage #80479) #105347 (2026-09-07); this PR is its Desktop projection, not the runtime fix
• Part of [Feature]: Guided picker for Subagent Model + Provider in Advanced Settings (Desktop + Dashboard) #67347
• Builds on merged fix(delegation): pinned children stop inheriting the parent fallback chain; delegation.fallback_providers declares their own (#80450, #65038, salvage #80479) #105347
• The separate Dashboard work remains in feat(web): guided picker for subagent model + provider (Dashboard half of #67347) #67557

Type of change

• New feature
• Documentation
• Tests
• Breaking change

Ownership boundary after #105347

Concern	Owner
Delegation runtime resolution and pin-aware fallback semantics	#105347 / current main
Desktop Models editor, profile-scoped persistence, and read-back	This PR
Dashboard UI	#67557
Generic primary-model fallback picker	#92942

Persistence and read-back contract

The editor binds the provider catalog, capability schema, configuration read, write, and verification read-back to one explicit {connectionId, profile} owner.

Selections remain local until Apply delegation settings. A successful PUT is not accepted as proof of persistence: the editor reads the same owner back and requires the saved delegation patch to match. Failed saves retain the draft for retry. If the backing delegation configuration changes while a draft is open, Apply is blocked until the user reloads. Responses from an earlier profile, gateway, or request generation are ignored.

Provider changes clear only stale delegation endpoint/auth routing fields. Model-only changes and fallback reorders preserve route metadata. Resetting fallback behavior writes the canonical key and clears legacy aliases so an old fallback cannot reappear.

Fallback matrix

Selection	Stored value	Runtime meaning (owned by #105347)
Default behavior	absent or null	Unpinned children inherit the parent chain; pinned children do not silently inherit
Use main fallbacks	"inherit"	Explicitly share the parent chain, including for a pinned child
No fallbacks	[]	Disable delegated-child fallbacks
Choose delegation fallbacks	ordered entries	Use exactly the declared delegation-scoped chain

Canonical delegation.fallback_providers wins. Legacy fallback_chain and fallback_model are read only when the canonical value is absent/null. "parent" remains a read-compatible alias for "inherit".

Files changed

• apps/desktop/src/api/config.ts
• apps/desktop/src/api/models-scope.test.ts
• apps/desktop/src/api/models.ts
• apps/desktop/src/app/settings/config-settings.tsx
• apps/desktop/src/app/settings/delegation-model-provider-field.test.tsx
• apps/desktop/src/app/settings/delegation-model-provider-field.tsx
• apps/desktop/src/app/settings/delegation-model-settings.test.tsx
• apps/desktop/src/app/settings/delegation-model-settings.tsx
• apps/desktop/src/app/settings/delegation-models-copy.ts
• apps/desktop/src/app/settings/delegation-models-state.test.ts
• apps/desktop/src/app/settings/delegation-models-state.ts
• hermes_cli/web_routers/config_env.py
• tests/hermes_cli/test_delegation_config_capability.py
• website/docs/user-guide/features/delegation-models.md

Collision and landing order

• fix(delegation): pinned children stop inheriting the parent fallback chain; delegation.fallback_providers declares their own (#80450, #65038, salvage #80479) #105347 is already merged and owns runtime behavior; this rebuild has zero runtime-file overlap.
• feat(desktop): add guided subagent model/provider picker (#67347) #67523's guided picker is superseded by this integrated Desktop carrier, with its source and authorship credited below.
• feat(web): guided picker for subagent model + provider (Dashboard half of #67347) #67557 and feat(desktop): searchable model and provider selects in Model settings #92942 are disjoint from this rebuilt file list.
• This PR should land before feat(voice): add Codex OAuth STT, TTS, and live voice #106640 (overlap: apps/desktop/src/api/config.ts) and One gateway owns every local session: CLI, TUI, Desktop (local), API, ACP, bots and cron attach to the same live conversation #106742 (overlap: apps/desktop/src/app/settings/config-settings.tsx); those branches should rebase afterward.

Local verification

• Focused Desktop tests: 31/31 passed
• Desktop TypeScript typecheck: passed
• Changed-file ESLint: passed
• Full Desktop lint: 0 errors (158 pre-existing warnings)
• Broad Desktop suite: 7,431 passed; 2 failed
  • both failures are in src/store/voice-prefs.test.ts
  • both reproduce unchanged on pristine current main 6f3e630
  • neither file nor behavior is touched here
• Python capability test: 1/1 passed
• Ruff on changed Python files: passed
• Windows-footgun diff audit: passed
• Contributor attribution audit: repo-wide audit reports 4 pre-existing unmapped contributors on current main (Leanolf+212****0991@…, evan-bradford@…, stiraspo@…, witcheer.eth@…) — none authored this PR's commit; this commit's lineage is covered by existing mappings plus its Co-authored-by trailers (webtecnica, Ayush Nangia). Repo-wide mapping repair is a separate main-level task, not owned by this PR.
• git diff --check: passed

Exact head: cbe9fa581ac28191eae5bc986c550b95cf712e3a. GitHub currently reports no workflow runs for this SHA. The three workflows created for the immediately preceding rebuilt head were stopped before jobs began with action_required; a NousResearch maintainer must approve the external-contributor workflows before exact-head CI evidence can run.

Contribution lineage

This integration adapts webtecnica's guided Desktop picker in #67523 and projects the runtime contract now owned by kshitijk4poor's merged #105347. That runtime work salvaged Ayush Nangia's pin/config matrix in #80479, including spfcraze's model-only-pin correction, and builds on #65052, Axl Ibiza's #80421, wz-heng's #80438, Teknium's #80465, devatnull's #81072, and TurgutKural's #101017. Product reports and requirements came from DavidMetcalfe (#67347), mlahatte (#65038), and ScotterMonk (#94629).

Original PRs retain their discussion, authorship, and review reservations.

[Enough1122]

AI code review — automated review for reference; please use your judgment.

Summary

Configurable delegation models and fallback chains: Desktop Models → Delegation UI (defaults + ordered backups with state/copy/docs), a delegation_fallbacks runtime capability from the config schema (not an editable key, since old backends persist unknown keys), and _resolve_child_fallback_chain ported from upstream #80479 — declared chains win, [] disables, pins never silently inherit the parent chain.

Findings

• Non-blocking — tools/delegate_tool_config.py:490: pinned=bool(override_provider or override_base_url or model) extends strictness to model-only pins — a pinned child cannot silently borrow the parent's recovery routes. Predictability-over-liveness for explicit pins is the right call, and tests pin parent-chain immutability (deepcopy, parent untouched).
• Non-blocking — tools/delegate_tool_fallback.py:70: error paths deliberately never include raw entries (they can contain credentials) and fall back to the pin-aware default. Good credential hygiene.
• Non-blocking — hermes_cli/web_routers/config_env.py:99: advertising support via capabilities rather than key-presence is the honest negotiation (old backends persist unknown keys). The legacy fallback_chain/fallback_model aliases are read-only compat and never overwrite a canonical []. Correct precedence.
• Non-blocking — the "inherit"/"parent" explicit opt-in string re-enables sharing deliberately — distinct from the old absent-key default, so existing configs do not silently widen. Good migration semantics.

Verified

• Scoped-fallback matrix tests, profile-loader wiring test, capability test, and Desktop field/state tests; parent _fallback_chain never mutated.

Verdict

Looks good. Careful pin semantics with credentials handled properly.