perf(desktop): stop full onboarding catalog reads on per-Session changes #5619

Problem

A change to one Session can make Desktop reread every Session for onboarding/readiness presentation. useOnboardingSnapshot pulls onboarding.getSnapshot() for every sessions:changed notification. Main's getSnapshot() calls listSessions() and rebuilds sessionSendOutcomes for every row. Preload obtains snapshots from ready Owner Hosts, uses the authenticated Owner results to seed its catalog, then calls listDesktopSessions() to return the merged Desktop snapshot.

This remains after #5532 made the ordinary Renderer catalog update a targeted sessions.get read. The onboarding path can still make the amount of Host, IPC, and projection work for one Session event depend on the entire catalog, including other ready Owner Hosts. It is especially costly for remote Hosts and active Sessions that emit repeated message-appended and turn-status-change notifications.

Source baseline: apache/maka@bc0786ee61219025ce89d9d7d4271bf7ce81edaa (2026-09-23): Renderer invalidation, Main snapshot, preload merge and seed, 32-item Host catalog page limit, and sequential stable page collection.

At the 32-item maximum, 1,000 rows require at least 32 catalog page requests and 5,000 rows at least 157. At an artificial 30 ms round trip, those sequential requests alone imply 0.96 s and 4.71 s transport lower bounds for a complete read, before disk, encoding, preload merging, and Renderer work. These are structural estimates, not measured Desktop latency or a claimed speedup. Real page counts can be higher when byte limits apply. The implementation PR must establish a reproducible current-main baseline.

Desired outcome — SPEC

A user with a large local or remote Session history can keep working while one Session changes. Onboarding state, the active Session's send-health notice, and stale-task badges remain correct, but a normal identified Session change does not reread every Owner catalog or resend every Session's outcome. Startup and recovery continue to provide a complete, authenticated catalog seed when that is required.

Scope and scenarios

1. Initial startup and Host attachment. Desktop obtains the default Host's onboarding state and the complete available Owner/Guest catalog coverage needed for the first useful view. An authenticated Owner snapshot may seed the catalog before an independent refresh; a failed later refresh must not blank that accepted seed. The default Host remains the source of default onboarding/connection selection. Other Owner Hosts contribute only their own Session rows and send outcomes. Guest Session rows continue to come from their mount authority.
2. Steady identified change. After a complete Owner catalog observation, a create, update, message append, Turn status change, rename, archive, model rebound, or delete affecting Session S updates the relevant catalog/readiness projection for S without a complete Session catalog read from every Host. Unchanged Sessions retain the same visible readiness and ordering. Repeated notifications for the same Session may be coalesced; the latest authoritative result wins.
3. First or last Session. Creating the first Session and deleting the last non-deleted Session update onboarding history state correctly. Existing one-time milestone semantics remain: deleting history must not reopen a settled onboarding guide. Archived and aborted history still counts according to the existing Core onboarding contract.
4. Connection or milestone change. A change that can affect many Sessions recomputes the affected readiness projections, including stale badges and the active send-health notice. A complete read is acceptable for this genuinely global event if needed for correctness; it must not become the path for ordinary identified Session events.
5. Reconnect, missed event, or incomplete coverage. Desktop may do a complete authoritative resync when it cannot prove its catalog/outcome coverage is current. A failed Host read keeps the last accepted authenticated projection for that Host and follows the existing error/retry behavior; it must not silently turn a missing outcome into a healthy one or erase unrelated Hosts' rows.

Rules and invariants

Failure, concurrency, and resource semantics

• Deduplicate/coalesce bursts without accumulating an unbounded backlog. If changes arrive during a read, a later accepted observation must cover them; stale responses are ignored or followed by a resync.
• Host disconnect, epoch replacement, unknown Session authority, or a catalog revision gap may trigger a full resync. Partial Host failure must preserve the last authenticated result for that Host and not block unrelated ready Hosts from updating.
• The normal identified-change path must make zero session.catalog.query list-start/list-continue requests once its Owner catalog coverage is complete. Targeted reads and fixed-size connection/readiness work may remain; their request count and transferred bytes must not grow with 100, 1,000, or 5,000 stored Sessions. Bootstrap, explicit global changes, and recovery resync are documented exceptions.
• No new fixed wall-clock latency claim is specified before an Electron baseline exists. The PR must report before/after median and p95 latency and relevant request/byte/work counts under identical fixtures, including artificial 30 ms RTT.

Non-goals and accepted tradeoffs

• Do not change onboarding product copy, which provider/model is selected, which Sessions count as history, or the meaning of stale-task badges.
• Do not replace the Host Session catalog protocol, rewrite TUI/CLI, virtualize the sidebar, or use this issue to redesign first paint; feat(desktop): decouple first paint from Runtime Host readiness #5494 and perf(desktop): publish session state at the granularity of change #5532 already changed adjacent paths.
• A complete initial/global/recovery scan is acceptable when it is the only way to establish authoritative coverage. This SPEC does not require O(1) startup or zero network calls per update.
• Do not duplicate credential/readiness policy in Renderer or add a second durable Session authority merely to improve a benchmark.
• A separate constant-time Renderer outcome store and sidebar stale-selector redesign are out of scope. This PR must document and measure the remaining local copy cost rather than claim end-to-end O(1) CPU work.

Acceptance and evidence

Planning notes (not SPEC)

First capture the current end-to-end request trace and an Electron baseline. Then write a short design report assigning the catalog/coverage, readiness projection, Host scope, and stale-response rules to one owner each. Implement the smallest boundary that satisfies R1–R5, remove the replaced full-refresh path, and keep only owner-level plus necessary seam regressions. The design may use targeted reads, existing catalog observations, or another mechanism; this issue intentionally specifies behavior rather than a cache or protocol shape.

Related: #2913, #4677; previously merged adjacent work: #5532 and #5494.

Prepared by OpenAI Codex on behalf of @wutongyuonce at the contributor's request. This issue contains a source-backed SPEC and planning evidence; no implementation or end-to-end performance result is claimed. The human contributor owns submission and review.