perf(desktop): make session switching fast under load

[OutThisLife]

Summary

Switching sessions in the desktop app could freeze the whole UI for several seconds on heavy, tool-rich chats — nothing scrollable, no text selection, clicks dead. Diagnosed from a user debug bundle (X1 Carbon, 14 GB RAM, a ~33k-token session stuck in retry, 5 detached backend sessions). The freeze is backend resume latency + accumulated agents + redundant renderer work, not one bug. (The originally-proposed "skip double-convert" was already implemented on main.)

• Defer the agent build on resume (the big one). session.resume built the AIAgent (MCP discovery, prompt/skill build) before returning, and the client awaits that RPC before it paints — so the whole switch blocked on the build. session.resume now defers the build by default for every caller: return the full display transcript immediately, register an upgradable live session, pre-warm the agent on a short timer (the deferred-build contract session.create already uses); _sess() still builds on demand if the first prompt beats it. The persisted runtime identity (model/provider/base_url/api_mode/reasoning/tier) is restored on the deferred build so it can't drop the provider. A caller that needs the agent built synchronously passes eager_build: true (used by the build-race test).

• Bound live agents with a soft LRU cap. Nothing capped how many in-memory agents accumulate; reconnecting often left detached sessions resident for the full 6h TTL (the report's detached_sessions=5). New max_live_sessions (default 16) evicts the least-recently-active detached sessions (no live client) — never a running, awaiting-input, mid-build, or live-transport one. Reopening re-resumes from disk. 0/null disables.

• Trim redundant renderer work on switch. On the prefetch-hit cold-resume path the code rebuilt a throwaway merged-message array (+ a ~1000-entry Map) that the downstream sameMessageList ref guard already drops — pure main-thread cost. Reuse the existing array ref instead.

Parity fixes (found while making deferred the default)

The deferred path goes through _start_agent_build instead of _init_session, which was missing two things:

• _enable_gateway_prompts() — approvals/clarify now route through gateway prompts on a deferred resume.
• background_review_callback / memory_notifications — the self-improvement "💾 …" summary now renders in-transcript instead of leaking to stdout (also fixes session.create sessions, which build through the same path).

ACP is unaffected (it uses its own session_manager, not this RPC); the Ink TUI already consumes the same lazy info shape from session.create and upgrades on the later session.info event.

Changes

• tui_gateway/server.py — deferred-by-default resume (eager_build opt-out); _start_agent_build restores full resume runtime overrides + wires review/memory callbacks; _enforce_session_cap / _session_is_lru_evictable / _max_live_sessions + enforcement from the idle reaper and after each new session.
• hermes_cli/config.py — max_live_sessions: 16 default (top-level, gateway.* fallback).
• apps/desktop/.../use-session-actions.ts — reuse $messages ref when the prefetch already painted it.

Code quality

Final commit DRYs the three deferred-session paths (cold resume / lazy watch / create) behind shared helpers — _deferred_session_record, _lazy_resume_info, _claim_or_reuse_live, _schedule_agent_build — collapsing three copies of the ~30-key session dict + lazy-info block to one each. No behavior change; suites stay green.

Test plan

• scripts/run_tests.sh tests/tui_gateway/ — all pass (incl. new deferred-default + LRU-cap tests; build-race + projection tests pinned to eager_build)
• scripts/run_tests.sh tests/hermes_cli/test_config*.py tests/hermes_cli/test_active_sessions.py — green
• desktop vitest run --environment jsdom (session-actions + state-cache) — green
• desktop tsc --noEmit + eslint — clean (0 errors)
• Manual: cold-switch a large tool-heavy session and confirm the transcript paints immediately, the window stays interactive while the agent pre-warms, and approvals + the review summary still surface.

[github-actions]

🔎 Lint report: bb/desktop-session-switch-perf vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 11265 on HEAD, 11263 on base (🆕 +2)

🆕 New issues (2):

Rule	Count
unresolved-attribute	2

First entries

run_agent.py:2989: [unresolved-attribute] unresolved-attribute: Object of type `Self@get_credits_spent_micros` has no attribute `_credits_session_start_micros`
tests/run_agent/test_credits_notices_toggle.py:76: [unresolved-attribute] unresolved-attribute: Unresolved attribute `_credits_session_start_micros` on type `AIAgent`

✅ Fixed issues (1):

Rule	Count
invalid-assignment	1

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to attribute `_credits_session_start_micros` of type `int`

Unchanged: 5938 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.