perf(session): track measured session-switch latency improvements

[franksong2702]

Problem

Switching between large sessions can still feel slow even though Hermes WebUI already windows the transcript and caches rendered HTML for some idle sessions.

This issue tracks measured, small-slice improvements to session-switch latency. It should not become a broad session renderer rewrite or a standalone instrumentation project.

Evidence so far

Local 8787 measurement on three real idle sessions showed duplicate transcript post-processing before #2166:

• highlightCode: 3 calls per switch
• addCopyButtons: 2 calls per switch
• PDF / HTML / Mermaid / KaTeX helpers: 2 calls per switch

After #2166, the same helper set runs once per switch.

Measured wall-clock numbers from the same local 8787 pass:

Session	Messages	Before first pass	After first pass	Before second pass	After second pass
20260513_112418_89ca08	1793	5266.7 ms	3037.5 ms	2732.5 ms	1350.3 ms
20260504_160031_1fd2bc	855	4198.1 ms	1668.0 ms	2215.1 ms	1298.4 ms
20260503_152835_357902	724	3251.5 ms	1182.4 ms	1116.9 ms	1249.9 ms

The wall-clock values include API, filesystem, sidebar, workspace, and browser runtime variance. The stable invariant is the duplicate helper-call reduction. This tracking issue should avoid turning those wall-clock values into fake precision.

Current slices

#2166 — consolidate transcript post-render processing

#2166 removes the most obvious duplicate frontend work:

• cached transcript path
• fresh transcript rebuild path
• idle loadSession() path no longer runs an extra highlightCode()

This is intentionally narrow and does not claim to fix every source of session-switch latency.

#2170 — skip CLI metadata lookup for native sessions

#2170 addresses the next measured backend bottleneck after #2166.

Local direct-route profiling showed native WebUI session metadata loads were still paying an unnecessary Agent/CLI metadata scan. Native WebUI sessions already have local metadata, so the CLI/messaging fallback path can be skipped for those sessions while preserved for imported CLI and messaging-backed sessions.

Measured local route timing for GET /api/session?messages=0&resolve_model=0 on 20260513_112418_89ca08 improved from median 662.82 ms to 1.71 ms.

#2171 — trim bounded tail response overhead

#2171 addresses tail-window response overhead for GET /api/session?messages=1&resolve_model=0&msg_limit=30.

Local profiling showed the response was inflated by historical session.tool_calls and spent avoidable time in response redaction. The slice keeps redaction and legacy tool-call fallback behavior, but:

• skips the full redactor for strings without likely credential markers
• omits historical tool_calls when returned messages already carry per-message tool metadata

Measured local route timing, with #2170's metadata scan removed in the harness, reduced representative tail-window responses from hundreds of milliseconds and hundreds of KB / MB down to low milliseconds and much smaller payloads.

#2171 currently has an unrelated Python 3.13 CI failure in tests/test_ctl_script.py; #2172 / #2173 track and fix that separate ctl.sh lifecycle issue.

Follow-up policy

Further work should remain profiling-first and fix-first:

• Use local or temporary profiling to identify the next real bottleneck.
• Do not add standalone debug/timing UI to the main repository unless it directly supports a concrete fix and maintainer feedback asks for it.
• Each follow-up PR should name the measured bottleneck it addresses.
• Each follow-up PR should include before/after evidence or an invariant regression test.
• Perf claims should distinguish deterministic call-count / payload reductions from noisy wall-clock measurements.

Possible future slices

These are candidates only if measurement justifies them:

1. Reduce avoidable side effects during session switches, for example workspace refresh or adjacent sidebar work that does not affect the visible switch result.
2. Investigate active/in-flight session cache behavior by caching only stable historical transcript content while keeping the live assistant segment separate.
3. Lazy-initialize heavy inline components such as Mermaid, PDF, HTML iframe, Excalidraw, or KaTeX only if artifact-heavy sessions prove this is the common slow path.
4. Consider Markdown rendering changes only if profiling proves Markdown conversion is the dominant bottleneck.

Non-goals

• No standalone instrumentation PR as the next step.
• No Markdown Web Worker unless timing proves Markdown rendering is the dominant bottleneck.
• No full incremental DOM diff rewrite as the first follow-up.
• No broad session renderer rewrite.
• No claim that Consolidate session post-render processing #2166, Skip CLI metadata lookup for native session loads #2170, or Trim session tail response overhead #2171 fully solve session-switch latency.
• No optimizing based only on one subjective slow session without a timing breakdown.

[franksong2702]

Opened follow-up PR #2170 to address the next measured session-switch bottleneck after #2166. Local profiling showed native WebUI session metadata loads were still paying an unnecessary Agent/CLI metadata scan; #2170 skips that scan for native WebUI sessions while keeping it for imported CLI and messaging-backed sessions. Real-state direct route timing on session 20260513_112418_89ca08 improved from median 662.82 ms to 1.71 ms for /api/session?messages=0&resolve_model=0.

[franksong2702]

Opened follow-up PR #2171 as the next measured session-switch slice after #2166 and #2170. Local profiling showed the tail-window /api/session?messages=1&resolve_model=0&msg_limit=30 response was inflated by historical session.tool_calls and spent avoidable time in response redaction. #2171 keeps redaction and legacy tool-call fallback behavior, but skips full redaction for strings without credential markers and omits historical tool_calls when returned messages already carry per-message tool metadata.

[nesquena-hermes]

Thanks for opening this as a measured tracking issue rather than a renderer rewrite — the discipline of "small slice + measured before/after" is exactly the right shape for session-switch perf work.

Acknowledging the three slices that have landed or are in flight:

• Consolidate session post-render processing #2166 — deduplicated transcript post-processing (highlightCode 3→1 per switch, addCopyButtons 2→1, PDF/HTML/Mermaid/KaTeX helpers 2→1). Already merged.
• Skip CLI metadata lookup for native session loads #2170 — skip Agent/CLI metadata scan for native WebUI sessions on the /api/session?messages=0&resolve_model=0 path. Median 662.82 ms → 1.71 ms on the cited real session.
• Trim session tail response overhead #2171 — tail-window response trim: skip full redaction for strings without credential markers + omit historical tool_calls when per-message tool metadata is already present.

Labeling tracking + performance, milestoning Milestone 2 — Power user features so the umbrella stays visible while individual slices land. To keep this from sliding into "broad renderer rewrite" territory, two soft guardrails I'd suggest enforcing on each subsequent slice:

1. Numbers before code. Each new slice ships with a before/after wall-clock number from the same local 8787 measurement methodology (median of N runs on a real idle session of the cited size). Without that, it's hard to tell whether a "perf" change is a no-op vs. a real win.
2. Per-slice scope budget. Single behavior, single hot path, ≤200 LOC. If a slice grows past that or starts touching unrelated rendering code, it should fork into its own focused issue rather than expand here.

Both #2170 and #2171 are within those guardrails, so this is more pinning the contract than gating anything. Will close when no measurable bottleneck remains and the umbrella has nothing actionable left.