refactor(settings): extract backend resolution

[ewen-poch]

Problem

SettingsService still owned backend selection, provider/model projection, framework preparation, and live Responses bridge/proxy generations. That mixed persistent settings orchestration with ephemeral runtime state and made the façade continue growing after runtime installation management was extracted.

Proposed change

• Add AgentBackendResolver as the owner of one backend resolution flow and its live bridge/proxy generations.
• Keep SettingsService as the existing façade; all public method signatures and type exports remain stable.
• Let ProviderAccountsModule project pure runtime targets and a separate secret-free reasoning capability profile.
• Preserve configured selection as { frameworkId }, with provider/model/reasoning late-bound at resolution time.
• Add an internal explicit target seam for a fixed provider/model/reasoning request. Known unavailable required models fail before runtime preparation; an unknown catalog preserves the exact requested model and never falls back.
• Add direct ownership and lifecycle coverage for bridge/proxy generations and ACP lease release.

flowchart LR
  F["SettingsService façade"] --> R["AgentBackendResolver"]
  R --> P["ProviderAccountsModule\nmodel and capability projection"]
  R --> M["AgentRuntimeManager\nexecutable and materialization"]
  R --> C["ConnectorSettingsModule\nenabled connector projection"]
  R --> B["Responses bridge / native proxy\ngeneration + lease ownership"]
  R --> O["ResolvedAgentBackend"]
  O --> A["AcpRuntime\nlease consumer + teardown"]

Loading

Scope and non-goals

• Internal architecture/state-ownership change only; no data model, data relationship, persistence schema, or user-interaction change.
• No changes to Electron preload/IPC, Web RPC/API map, CLI/SDK, Task API, or ACP public contracts.
• Specialist, Permission, and Compute behavior and their current cross-surface capability asymmetry remain unchanged.
• No Electron adapter install/uninstall changes; the rollback boundary from fix(runtime): roll back Electron adapter installation #589 remains intact.
• Forward-compatible with [Feature]: Provider-neutral multi-agent research orchestration #458 through an internal, non-secret explicit target only. This PR does not add orchestration metadata, session trees, permissions, budgets, events, persistence, or public APIs.
• Local planning documents under docs/internal/ remain ignored and are not part of this PR.

Acceptance criteria and validation

All checks below ran after the final material edit and independent Standards, Spec, and cross-surface reviews reported no remaining P0-P2 findings.

• Provider target projection, exact required-model semantics, secret-free capability lookup, explicit/configured selection, framework delegation, generation isolation, and cleanup -> npm test -- --run src/main/settings/backend-resolver.test.ts src/main/settings/provider-accounts.test.ts -> 27/27 passed.
• Settings façade, bridge/proxy integration, IPC, and ACP lease lifecycle -> focused Settings/ACP suite -> 571/571 passed.
• Node and Web type contracts -> npm run typecheck -> passed.
• Repository lint -> npm run lint -> 0 errors; 23 pre-existing warnings.
• Web transport contract -> npm run check:web-api-map -> passed, no generated API change.
• CLI/SDK contract -> npm run test:cli -> 29/29 passed.
• Full repository regression -> npm test -> 636 files passed, 15 skipped; 9,407 tests passed, 184 skipped.

Uncovered risk: real provider processes and external APIs are not launched by the unit suite. The resolver keeps the existing framework adapters and provider preparation code paths, while fakes and loopback integration tests cover their ownership and cleanup contracts.

Review focus

• AgentBackendResolver constructor remains side-effect free; resources start only during resolution.
• Plaintext credentials exist only in ephemeral backend targets, while reasoning capability lookup remains secret-free.
• Overlapping bridge/proxy generations retain independent effort/reviewer state and release idempotently.
• Configured selections continue late-binding current settings; explicit targets remain fixed and private to the resolver.
• Existing Electron/Web/CLI/Task/ACP and Specialist/Permission/Compute contracts remain unchanged.

Relates to #458.

[github-actions]

Codex Review

Verdict: mergeable

No actionable findings.

Summary: Static inspection of the requested diff, callers, tests, configuration, and repository standards found no concrete merge-blocking defects. Branch and pull-request title prechecks are valid.