feat(desktop): paint cached transcripts on session click (switch-paint)

apps/desktop/electron/main.ts

@@ -7507,6 +7507,28 @@ ipcMain.handle('hermes:render-cache:read', (_event, gatewayUrl, activeStoredSess
   }
 })
 
+// Per-session transcript read (switch-paint; Ace 2026-07-11): lets the click
+// path paint a cached transcript instantly while the live prefetch runs. Same
+// gateway-URL resolution + fail-open contract as the boot read above.
+ipcMain.handle('hermes:render-cache:read-transcript', (_event, gatewayUrl, storedSessionId) => {
+  try {
+    let url = String(gatewayUrl || '').trim()
+    if (!url) {
+      const config = readDesktopConnectionConfig()
+      if (config.mode === 'remote' && config.remote?.url) {
+        url = String(config.remote.url).trim()
+      }
+    }
+    const cache = getRenderCache(url)
+    if (!cache || !storedSessionId) {
+      return null
+    }
+    return cache.readTranscript(String(storedSessionId))
+  } catch {
+    return null
+  }
+})
+
 // Reconcile observability (Phase 0 RC4): the renderer reports how many rows
 // differed between the cached paint and the first live snapshot. rows=0 means
 // the cache matched live exactly — I1's "reconciles within one cycle" held.

apps/desktop/electron/preload.ts

@@ -7,6 +7,9 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   renderCache: {
     read: (gatewayUrl, activeStoredSessionId) =>
       ipcRenderer.invoke('hermes:render-cache:read', gatewayUrl, activeStoredSessionId),
+    // Per-session transcript read (switch-paint): cheap, returns {rows}|null.
+    readTranscript: (gatewayUrl, storedSessionId) =>
+      ipcRenderer.invoke('hermes:render-cache:read-transcript', gatewayUrl, storedSessionId),
     putSessions: (gatewayUrl, data) => ipcRenderer.send('hermes:render-cache:put-sessions', gatewayUrl, data),
     putStatus: (gatewayUrl, data) => ipcRenderer.send('hermes:render-cache:put-status', gatewayUrl, data),
     putTranscript: (gatewayUrl, storedSessionId, rows) =>

apps/desktop/src/app/render-cache-hydration.test.ts

@@ -16,6 +16,7 @@ import {
   computeListDivergence,
   cullRenderCacheSession,
   hydrateFromRenderCache,
+  normalizeCachedTranscriptRows,
   pushStatusToRenderCache,
   pushTranscriptToRenderCache,
   reconcileRenderCache
@@ -226,7 +227,7 @@ describe('transcript paint (chat pane)', () => {
         gatewayUrl: 'http://studio:9119',
         sessions: null,
         status: null,
-        transcript: { storedSessionId: 'sid', rows: [{ text: 'hello' }] }
+        transcript: { storedSessionId: 'sid', rows: [{ role: 'user', parts: [{ type: 'text', text: 'hello' }] }] }
       })
     })
     const setMessages = vi.fn()
@@ -239,7 +240,7 @@ describe('transcript paint (chat pane)', () => {
       setMessages
     })
     expect(result.transcriptPainted).toBe(true)
-    expect(setMessages).toHaveBeenCalledWith([{ text: 'hello' }])
+    expect(setMessages).toHaveBeenCalledWith([{ role: 'user', parts: [{ type: 'text', text: 'hello' }] }])
   })
 
   it('never paints into a NON-empty messages store, and never without a remembered session', async () => {
@@ -249,7 +250,7 @@ describe('transcript paint (chat pane)', () => {
         gatewayUrl: 'http://studio:9119',
         sessions: null,
         status: null,
-        transcript: { storedSessionId: 'sid', rows: [{ text: 'hello' }] }
+        transcript: { storedSessionId: 'sid', rows: [{ role: 'user', parts: [{ type: 'text', text: 'hello' }] }] }
       })
     })
     const setMessages = vi.fn()

apps/desktop/src/app/render-cache-hydration.ts

@@ -17,7 +17,9 @@
  * Everything here is fail-open: cache errors degrade to today's boot (I3).
  */
 
-import type { SessionInfo } from '@/types/hermes'
+import { toChatMessages } from '@/lib/chat-messages'
+import type { ChatMessage } from '@/lib/chat-messages'
+import type { SessionInfo, SessionMessage } from '@/types/hermes'
 
 export interface CachedSessionList {
   sessions: SessionInfo[]
@@ -69,15 +71,17 @@ export async function hydrateFromRenderCache(deps: {
     // thread-switch branch, which publishes pending.state.messages unmerged).
     let transcriptPainted = false
     const cachedTranscript = result.transcript as { rows?: unknown[] } | null
+    const transcriptRows = Array.isArray(cachedTranscript?.rows)
+      ? normalizeCachedTranscriptRows(cachedTranscript!.rows)
+      : []
     if (
       deps.setMessages &&
       deps.getMessages &&
       deps.rememberedSessionId &&
-      Array.isArray(cachedTranscript?.rows) &&
-      cachedTranscript!.rows.length > 0 &&
+      transcriptRows.length > 0 &&
       deps.getMessages().length === 0
     ) {
-      deps.setMessages(cachedTranscript!.rows)
+      deps.setMessages(transcriptRows)
       transcriptPainted = true
     }
 
@@ -159,6 +163,50 @@ export function reconcileRenderCache(opts: {
   }
 }
 
+/**
+ * Read a cached transcript for ANY session (the switch-paint path; Ace
+ * 2026-07-11: "cache them so we never wait when we click on a session").
+ * Returns the cached rows or null. Fail-open: any error is a miss. Rows come
+ * back in whichever shape the writer stored (raw SessionMessage from the
+ * preloader, converted ChatMessage from the write-through) — callers paint
+ * via normalizeCachedTranscriptRows.
+ */
+export async function readCachedTranscript(storedSessionId: string | null): Promise<unknown[] | null> {
+  try {
+    const api = renderCacheApi()
+    if (!api?.readTranscript || !storedSessionId) {
+      return null
+    }
+    const result = (await api.readTranscript(null, storedSessionId)) as { rows?: unknown[] } | null
+    const rows = Array.isArray(result?.rows) ? result!.rows : null
+    return rows && rows.length > 0 ? rows : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Normalize cached transcript rows to ChatMessage[] for painting. Two writer
+ * shapes exist: the transcript preloader stores raw SessionMessage rows; the
+ * active-session write-through stores converted ChatMessage rows (they carry
+ * `parts: []`). Sniff and convert; anything unconvertible comes back empty
+ * (callers treat empty as a miss and fall through to the network).
+ */
+export function normalizeCachedTranscriptRows(rows: unknown[]): ChatMessage[] {
+  try {
+    if (!Array.isArray(rows) || rows.length === 0) {
+      return []
+    }
+    const first = rows[0] as { parts?: unknown }
+    if (first != null && typeof first === 'object' && Array.isArray(first.parts)) {
+      return rows as ChatMessage[]
+    }
+    return toChatMessages(rows as SessionMessage[])
+  } catch {
+    return []
+  }
+}
+
 /** Push a live status snapshot into the cache (fire-and-forget). */
 export function pushStatusToRenderCache(gatewayUrl: string | null, status: unknown): void {
   try {

apps/desktop/src/app/session/hooks/use-session-actions/index.ts

@@ -11,7 +11,7 @@ import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { $activeGatewayProfile, $newChatProfile, ensureGatewayProfile, normalizeProfileKey } from '@/store/profile'
 import { resolveNewSessionCwd, tombstoneSessions, untombstoneSessions } from '@/store/projects'
 
-import { cullRenderCacheSession } from '../../../render-cache-hydration'
+import { cullRenderCacheSession, normalizeCachedTranscriptRows, readCachedTranscript } from '../../../render-cache-hydration'
 import {
   $connection,
   $currentCwd,
@@ -339,6 +339,24 @@ export function useSessionActions({
         setActiveSessionId(null)
         activeSessionIdRef.current = null
         setMessages([])
+
+        // Switch-paint from the render cache (Ace 2026-07-11): for a cold
+        // target, paint the cached transcript instantly while the live
+        // prefetch below runs. Read is async (~ms IPC + disk); guarded so it
+        // only applies while THIS resume is current and nothing live (or a
+        // newer click) has painted yet — the live prefetch/resume wholesale-
+        // replaces these rows when it lands (same SWR contract as boot).
+        void readCachedTranscript(storedSessionId)
+          .then(cachedRows => {
+            if (!cachedRows || !isCurrentResume() || $messages.get().length > 0) {
+              return
+            }
+            const painted = normalizeCachedTranscriptRows(cachedRows)
+            if (painted.length > 0) {
+              setMessages(painted)
+            }
+          })
+          .catch(() => undefined)
       }
 
       // Swap the single live gateway to this session's profile before any
@@ -459,6 +477,31 @@ export function useSessionActions({
         // Watch windows skip the prefetch — lazy resume attaches the live mirror.
         const prefetchPromise = watchWindow ? null : getSessionMessages(storedSessionId, sessionProfile)
 
+        // Switch-paint from the render cache (Ace 2026-07-11: first click on a
+        // session shouldn't wait on the network). If this session's transcript
+        // is cached (transcript preloader / write-through), paint it NOW while
+        // the prefetch + resume run. Interim paint only: it never feeds
+        // localSnapshot, so the live prefetch/resume below wholesale-replaces
+        // it (same I5 discipline as the boot paint).
+        if (!watchWindow && $messages.get().length === 0) {
+          readCachedTranscript(storedSessionId)
+            .then(rows => {
+              if (!rows || !isCurrentResume()) {
+                return
+              }
+              // A live payload may already have landed while the cache read
+              // resolved; never clobber it with the cached copy.
+              if ($messages.get().length > 0) {
+                return
+              }
+              const painted = normalizeCachedTranscriptRows(rows)
+              if (painted.length > 0) {
+                setMessages(painted)
+              }
+            })
+            .catch(() => undefined)
+        }
+
         const resumePromise = requestGateway<SessionResumeResponse>('session.resume', {
           session_id: storedSessionId,
           cols: 96,

apps/desktop/src/app/switch-cache-paint.test.ts

@@ -0,0 +1,86 @@
+// Switch-paint from the render cache (Ace 2026-07-11: "clicking a session for
+// the first time doesn't feel snappy"). Contract under test:
+//  1. readCachedTranscript returns rows for a cached session, null otherwise;
+//     it NEVER throws (fail-open) — a broken preload API is a miss.
+//  2. normalizeCachedTranscriptRows handles BOTH writer shapes: raw
+//     SessionMessage rows (transcript preloader) convert via toChatMessages;
+//     already-converted ChatMessage rows (write-through) pass through.
+//  3. Empty/garbage normalizes to [] — the switch falls through to the
+//     network, never paints a blank.
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { normalizeCachedTranscriptRows, readCachedTranscript } from './render-cache-hydration'
+
+function installApi(readTranscript: unknown) {
+  ;(window as any).hermesDesktop = { renderCache: { readTranscript } }
+}
+
+describe('readCachedTranscript (switch-paint)', () => {
+  beforeEach(() => {
+    delete (window as any).hermesDesktop
+  })
+
+  it('returns cached rows for a hit', async () => {
+    installApi(vi.fn().mockResolvedValue({ rows: [{ role: 'user', content: 'hi' }] }))
+    const rows = await readCachedTranscript('s1')
+    expect(rows).toEqual([{ role: 'user', content: 'hi' }])
+  })
+
+  it('passes a null gatewayUrl (main resolves it) and the session id', async () => {
+    const read = vi.fn().mockResolvedValue({ rows: [1] })
+    installApi(read)
+    await readCachedTranscript('s42')
+    expect(read).toHaveBeenCalledWith(null, 's42')
+  })
+
+  it('misses on null payload, empty rows, and missing id', async () => {
+    installApi(vi.fn().mockResolvedValue(null))
+    expect(await readCachedTranscript('s1')).toBeNull()
+
+    installApi(vi.fn().mockResolvedValue({ rows: [] }))
+    expect(await readCachedTranscript('s1')).toBeNull()
+
+    installApi(vi.fn().mockResolvedValue({ rows: [1] }))
+    expect(await readCachedTranscript(null)).toBeNull()
+    expect(await readCachedTranscript('')).toBeNull()
+  })
+
+  it('fail-open: missing bridge, missing method, rejecting IPC are all misses', async () => {
+    expect(await readCachedTranscript('s1')).toBeNull() // no hermesDesktop at all
+
+    ;(window as any).hermesDesktop = { renderCache: {} } // no readTranscript method
+    expect(await readCachedTranscript('s1')).toBeNull()
+
+    installApi(vi.fn().mockRejectedValue(new Error('ipc down')))
+    expect(await readCachedTranscript('s1')).toBeNull()
+  })
+
+  it('tolerates a malformed payload (rows not an array)', async () => {
+    installApi(vi.fn().mockResolvedValue({ rows: 'garbage' }))
+    expect(await readCachedTranscript('s1')).toBeNull()
+  })
+})
+
+describe('normalizeCachedTranscriptRows (dual writer shapes)', () => {
+  it('passes ChatMessage-shaped rows (write-through) straight through', () => {
+    const rows = [{ id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] }]
+    expect(normalizeCachedTranscriptRows(rows)).toBe(rows)
+  })
+
+  it('converts raw SessionMessage rows (preloader) via toChatMessages', () => {
+    const raw = [
+      { role: 'user', content: 'hello' },
+      { role: 'assistant', content: 'hey there' }
+    ]
+    const out = normalizeCachedTranscriptRows(raw)
+    expect(out.length).toBeGreaterThan(0)
+    expect(out[0]).toHaveProperty('parts')
+    expect(out[0].role).toBe('user')
+  })
+
+  it('empty/garbage input normalizes to [] (a miss, never a blank paint)', () => {
+    expect(normalizeCachedTranscriptRows([])).toEqual([])
+    expect(normalizeCachedTranscriptRows(null as never)).toEqual([])
+    expect(normalizeCachedTranscriptRows('nope' as never)).toEqual([])
+  })
+})

apps/desktop/src/app/transcript-preload.test.ts

@@ -56,7 +56,7 @@ describe('preloadTranscripts', () => {
       gatewayUrl: 'http://g',
       sessions: [s('cached'), s('empty'), s('real')],
       freshCached: new Set(['cached']),
-      fetchMessages: (async (id: string) => ({ messages: id === 'empty' ? [] : [{ x: 1 }] })) as never,
+      fetchMessages: (async (id: string) => ({ messages: id === 'empty' ? [] : [{ role: 'user', content: 'hi' }] })) as never,
       push: ((_u: string, id: string) => pushed.push(id)) as never,
       sleep: noSleep
     })
@@ -71,7 +71,7 @@ describe('preloadTranscripts', () => {
       sessions: [s('bad'), s('good')],
       fetchMessages: (async (id: string) => {
         if (id === 'bad') throw new Error('boom')
-        return { messages: [{ x: 1 }] }
+        return { messages: [{ role: 'user', content: 'hi' }] }
       }) as never,
       push: ((_u: string, id: string) => pushed.push(id)) as never,
       sleep: noSleep
@@ -87,7 +87,7 @@ describe('preloadTranscripts', () => {
       sessions: [s('a'), s('b'), s('c')],
       fetchMessages: (async () => {
         calls += 1
-        return { messages: [{ x: 1 }] }
+        return { messages: [{ role: 'user', content: 'hi' }] }
       }) as never,
       push: (() => undefined) as never,
       sleep: noSleep,
@@ -107,11 +107,31 @@ describe('preloadTranscripts', () => {
       sessions: [s('x', { profile: 'daedalus' } as never)],
       fetchMessages: (async (id: string, profile?: string | null) => {
         seen.push([id, profile])
-        return { messages: [{ x: 1 }] }
+        return { messages: [{ role: 'user', content: 'hi' }] }
       }) as never,
       push: (() => undefined) as never,
       sleep: noSleep
     })
     expect(seen).toEqual([['x', 'daedalus']])
   })
+
+  it('stores ChatMessage-shaped rows (parts[]), not raw SessionMessage rows', async () => {
+    const pushedRows: unknown[][] = []
+    await preloadTranscripts({
+      gatewayUrl: 'http://g',
+      sessions: [s('a')],
+      fetchMessages: (async () => ({
+        messages: [
+          { role: 'user', content: 'hi' },
+          { role: 'assistant', content: 'yo' }
+        ]
+      })) as never,
+      push: ((_u: string, _id: string, rows: unknown[]) => pushedRows.push(rows)) as never,
+      sleep: noSleep
+    })
+    expect(pushedRows).toHaveLength(1)
+    for (const row of pushedRows[0] as Array<{ parts?: unknown }>) {
+      expect(Array.isArray(row.parts)).toBe(true)
+    }
+  })
 })

apps/desktop/src/app/transcript-preload.ts

@@ -20,6 +20,7 @@
  */
 
 import { getSessionMessages } from '@/hermes'
+import { toChatMessages } from '@/lib/chat-messages'
 import type { SessionInfo } from '@/types/hermes'
 
 import { pushTranscriptToRenderCache } from './render-cache-hydration'
@@ -76,7 +77,11 @@ export async function preloadTranscripts(deps: PreloadDeps): Promise<number> {
     }
     try {
       const result = await fetchMessages(session.id, session.profile)
-      const rows = Array.isArray(result?.messages) ? result.messages : []
+      const raw = Array.isArray(result?.messages) ? result.messages : []
+      // Store in ChatMessage shape (what setMessages renders) so the paint
+      // path never converts on click. toChatMessages is the same conversion
+      // the live prefetch applies.
+      const rows = raw.length > 0 ? toChatMessages(raw) : []
       if (rows.length > 0) {
         push(gatewayUrl, session.id, rows)
         cached += 1