fix(desktop): route host.warmProfile through the guarded prewarm resolver

[jahfaliabdulrahman-dev]

What does this PR do?

host.warmProfile (the plugin SDK surface that bot-row calls on onPointerEnter) dialed openGatewayForProfile directly — bypassing the pool-saturation guard, hover dwell, and per-profile throttle that prewarmProfileBackend enforces for the built-in rail.

Consequence: a pointer sweep across a plugin roster spawns profile backends at pointer speed. With the pool at its default cap (3), the next profile's real spawn queues behind them and times out after 30s — the profile's surface then hangs on an endless spinner while every other profile renders fine. Reproduced on a 4-profile setup: waiting for a free local slot (3/3 busy, 1 queued) repeating every ~30s, self-healing only after the 10-minute idle reaper harvests the pool.

This PR delegates warmProfile to prewarmProfileBackend, so every speculative warm shares one resolver and one policy (the design guide's single-resolver rule). Behavior contract of the old SDK path is preserved: blank names are ignored, the active profile is a no-op, and failures stay swallowed (the click path re-runs its own ensure and owns error UX). Only the speculative head start is gated.

Behavior of openRosterBot/real clicks is untouched — they dial on demand exactly as before.

Related Issue

Fixes #103631

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• apps/desktop/src/sdk/index.ts — warmProfile now delegates to prewarmProfileBackend (same saturation guard + 60s throttle + active-profile no-op as the rail hover path); blank-name guard preserved; import added
• apps/desktop/src/sdk/index.test.ts — contract tests for the warm path: dial passes through the guarded resolver when a slot is free, speculative spawn is skipped when every slot is occupied (3/3), blank names never dial

How to Test

1. cd apps/desktop && npx vitest run src/sdk/index.test.ts src/store/profile.test.ts src/plugins/hermes-bots/bot-row.test.tsx — all green (14 + 26 tests)
2. Saturation proof: with 3 secondary profile backends open, sweep the pointer across the Bots roster, then open a 4th profile's settings — before this PR the page spins for 30s+; after it, the warm attempt is skipped and the real open proceeds once the user actually clicks
3. npx tsc --noEmit -p tsconfig.json — clean; npx eslint src/sdk/index.ts src/sdk/index.test.ts — clean; npx prettier --check — clean

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass — desktop TS change; the relevant vitest suites run green (above); Python suite untouched
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 26.6 (Apple Silicon, arm64)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A — N/A (docstring of the SDK surface updated in place)
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A — renderer-only change, platform-agnostic
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A — N/A

Screenshots / Logs

Repro log (main, before fix) — 6 consecutive spawn timeouts for the 4th profile:

Profile backend "marketing" waiting for a free local slot (3/3 busy, 1 queued)
Hermes backend for profile "marketing" failed to start: Local backend start for "marketing" timed out while waiting for a free slot.

After the fix, a saturated pool yields no speculative spawn attempt at all (covered by the skips the speculative spawn when every pool slot is occupied contract test).

[Enough1122]

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

PR 103634 — fix(desktop): route host.warmProfile through the guarded prewarm resolver

Summary: host.warmProfile now delegates to prewarmProfileBackend, inheriting the pool-saturation guard, hover dwell, and per-profile throttle instead of dialing openGatewayForProfile directly — fixing the pointer-sweep spawn storm from #91545. Small, well-explained change. Two verification questions, both non-blocking.

Non-blocking findings:

1. apps/desktop/src/sdk/index.ts:101-111 — the old code swallowed failures explicitly (void …​.catch(() => undefined)); the new code relies on prewarmProfileBackend never rejecting (or handling its own errors). If the resolver can throw/reject on some path, warmProfile now surfaces an unhandled rejection from hover handlers. Please confirm the resolver is internally total, or re-add the .catch at this call site.
2. apps/desktop/src/sdk/index.ts:104-107 — the name === $activeGatewayProfile.get() early-out was removed; the docstring says the no-op for shared-remote routes and the primary is preserved, but it is ambiguous whether that guarantee now lives in prewarmProfileBackend. If the resolver lacks the active-profile check, hovering the already-active profile does a redundant pool dial each time. Please confirm the check moved rather than vanished.
3. Test gap (minor): the new contract tests pin saturation vs. free-slot and blank names, but not the dwell/throttle inheritance that is the actual [Bug] Desktop profile switching gets progressively slower during long-running sessions #91545 fix (rapid repeated warmProfile calls → single dial). If prewarmProfileBackend's own suite already covers throttle semantics, this is fine — otherwise one test simulating a pointer sweep would lock the regression.

No correctness concerns with the delegation itself; good to go once (1) and (2) are confirmed.

[jahfaliabdulrahman-dev]

Thanks for the automated review — all three findings check out as already-covered, with receipts from the current branch:

1. Failure swallowing — moved, not lost. prewarmProfileBackend is internally total: its final statement is the same fire-and-forget chain the SDK used to have, now in the resolver (apps/desktop/src/store/profile.ts:440):

openGatewayForProfile(key).catch(() => undefined)

Since warmProfile now just calls it (sync, no promise escapes the function), a hover handler cannot observe a rejection from this path.

2. Active-profile no-op — moved, not vanished. The first guard inside prewarmProfileBackend is exactly the removed check (apps/desktop/src/store/profile.ts:417):

if (key === normalizeProfileKey($activeGatewayProfile.get())) {
  return
}

Hovering the already-active profile returns before any pool dial — same guarantee, now enforced for every caller of the resolver, not just the SDK surface.

3. Dwell/throttle inheritance — covered in the resolver's own suite. apps/desktop/src/store/profile.test.ts pins both halves:

• 'throttles repeat pre-warms for the same profile within the interval' (line 174) — the 60s per-profile throttle (PREWARM_MIN_INTERVAL_MS, profile.ts:411/424), i.e. the rapid-repeat → single-dial behavior suggested
• 'skips pre-warm when the pool is saturated (#91545 evict/respawn cascade)' (line 190) — the saturation guard

Since the delegation routes every warmProfile call through that resolver, those existing tests now bound the SDK path too. No new test added to avoid duplicating a contract already owned by the resolver's suite (happy to add a thin sweep-simulation test in sdk/index.test.ts if reviewers prefer the regression locked at the SDK boundary as well — say the word).

No code changes needed from this review; the delegation itself was the fix. Happy to adjust if a maintainer weighs in differently.

[teknium1]

Thanks @jahfaliabdulrahman-dev — Landed on main via #108107 (merge dbc5d7c) — your commit is on main as-is under your authorship, rebase-merged. The same salvage also routed host.warmAgent through the guarded resolver, so the class is closed. Thanks!