Skip to content

The agent that grows with you

perf(desktop): suppress hidden terminal DOM rows only

ghgoodreau915fb1b87578
diff --git a/apps/desktop/ENGINEERING.md b/apps/desktop/ENGINEERING.md
index c7a6e2a0cea..95643663d5f 100644
--- a/apps/desktop/ENGINEERING.md
+++ b/apps/desktop/ENGINEERING.md
@@ -155,6 +155,14 @@ reopens the gesture-less forced-navigation class the advisory closed.
- Unchanged retained snapshots must not republish the terminal store. Closing
the last mounted writer must enforce the cold agent-terminal retention budget
even when no later output arrives.
+- Hidden terminals stay mounted and keep parsing output. Suppress only their
+ DOM rows, not the measurable host/helpers or terminal state. Do not reduce
+ scrollback or replace parser state to save painting work. WebGL surfaces remain
+ unchanged; hidden DOM-row suppression must leave fitting and font helpers measurable.
+ Register an agent-terminal writer before recovering its matching process
+ snapshot. A quiet tab can reopen after cold eviction without any new registry
+ notification; recovery must not duplicate live output or exempt cold entries
+ from the retention budget.
## Nous free tier: state is pulled, never latched in the renderer
diff --git a/apps/desktop/src/app/right-sidebar/terminal/agent-terminal-recovery.test.tsx b/apps/desktop/src/app/right-sidebar/terminal/agent-terminal-recovery.test.tsx
new file mode 100644
index 00000000000..8541bdeeb0f
--- /dev/null
+++ b/apps/desktop/src/app/right-sidebar/terminal/agent-terminal-recovery.test.tsx
@@ -0,0 +1,147 @@
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { $backgroundStatusBySession, reconcileBackgroundProcesses } from '@/store/composer-status'
+
+import {
+ registerAgentTerminalWriter,
+ syncAgentTerminalSnapshot,
+ writeAgentTerminalChunk
+} from './agent-terminal-stream'
+import { $activeTerminalId, $terminals, closeTerminal, openAgentTerminal } from './terminals'
+import { useAgentTerminal } from './use-agent-terminal'
+import { TerminalWorkspace } from './workspace'
+
+const screens = vi.hoisted(() => new Map<string, string[]>())
+
+// Keep the store, workspace, attachment hook and stream real; only the xterm
+// renderer and instance chrome are replaced so each tab's writes are observable.
+vi.mock('@xterm/xterm', () => ({
+ Terminal: class {
+ readonly rows = 24
+ readonly unicode = { activeVersion: '6' }
+ readonly writes: string[] = []
+ options: Record<string, unknown>
+
+ constructor(options: Record<string, unknown>) {
+ this.options = { ...options }
+ }
+
+ open(host: HTMLElement) {
+ screens.set(host.dataset.procId!, this.writes)
+ }
+
+ write(chunk: string) {
+ this.writes.push(chunk)
+ }
+
+ attachCustomKeyEventHandler = vi.fn()
+ clearSelection = vi.fn()
+ dispose = vi.fn()
+ focus = vi.fn()
+ getSelection = vi.fn(() => '')
+ loadAddon = vi.fn()
+ onSelectionChange = vi.fn(() => ({ dispose: vi.fn() }))
+ refresh = vi.fn()
+ selectAll = vi.fn()
+ }
+}))
+
+vi.mock('@xterm/addon-fit', () => ({
+ FitAddon: class {
+ fit = vi.fn()
+ }
+}))
+
+vi.mock('@xterm/addon-unicode11', () => ({ Unicode11Addon: class {} }))
+vi.mock('@xterm/addon-web-links', () => ({ WebLinksAddon: class {} }))
+vi.mock('@xterm/addon-webgl', () => ({
+ WebglAddon: class {
+ clearTextureAtlas = vi.fn()
+ dispose = vi.fn()
+ onContextLoss = vi.fn()
+ }
+}))
+
+vi.mock('@/themes/context', () => ({
+ useTheme: () => ({ renderedMode: 'dark', theme: { terminal: {} }, themeName: 'test' })
+}))
+
+vi.mock('./instance', () => ({
+ AgentTerminalInstance: (props: { active: boolean; id: string; procId: string }) => {
+ const { hostRef } = useAgentTerminal(props)
+
+ return <div data-proc-id={props.procId} ref={hostRef} />
+ },
+ TerminalInstance: () => null
+}))
+
+afterEach(() => {
+ cleanup()
+ $terminals.set([])
+ $activeTerminalId.set(null)
+ $backgroundStatusBySession.set({})
+ screens.clear()
+ Reflect.deleteProperty(document, 'fonts')
+})
+
+describe('quiet agent terminal recovery', () => {
+ it('reopens an evicted tab from an unchanged registry exactly once while other writers remain mounted', async () => {
+ Object.defineProperty(document, 'fonts', {
+ configurable: true,
+ value: { load: vi.fn().mockResolvedValue([]) }
+ })
+ const procs = Array.from({ length: 26 }, (_, index) => ({
+ command: `quiet-command-${index}`,
+ output_tail: `snapshot-marker-${index}\r\n`,
+ session_id: `quiet-${index}`,
+ status: 'running'
+ }))
+ reconcileBackgroundProcesses('other-session', procs.slice(0, 25))
+ reconcileBackgroundProcesses('target-session', procs.slice(25))
+ const background = $backgroundStatusBySession.get()
+ const target = procs[25]!
+ const expected = `$ ${target.command}\r\n${target.output_tail}`
+
+ render(<TerminalWorkspace onAddSelectionToChat={() => {}} />)
+ await waitFor(() => expect(screens.size).toBe(26))
+ const original = screens.get(target.session_id)!
+ expect(original.join('')).toBe(expected)
+ const neighbor = screens.get(procs[24]!.session_id)!
+ const neighborOutput = neighbor.join('')
+ const tab = $terminals.get().find(entry => entry.procId === target.session_id)!
+
+ act(() => closeTerminal(tab.id))
+ expect($terminals.get()).toHaveLength(25)
+ // The remaining mounted writers already exceed the cache's 24-process
+ // budget: closing must really discard this tab, not grant a cache exemption.
+ const replay = vi.fn()
+ const stopProbe = registerAgentTerminalWriter(target.session_id, replay)
+ expect(replay).not.toHaveBeenCalled()
+ stopProbe()
+
+ act(() => openAgentTerminal(target.session_id, target.command))
+ await waitFor(() => expect(screens.get(target.session_id)).not.toBe(original))
+ const recovered = screens.get(target.session_id)!
+ expect($backgroundStatusBySession.get()).toBe(background)
+ expect(recovered.join('')).toBe(expected)
+ expect(neighbor.join('')).toBe(neighborOutput)
+ // A delayed cleanup from the old attachment must not detach its replacement.
+ stopProbe()
+
+ // Both an unchanged registry snapshot and a later snapshot containing live
+ // bytes must respect the restored fence rather than duplicate either source.
+ syncAgentTerminalSnapshot(target.session_id, target.output_tail)
+ const live = 'live-after-reopen\r\n'
+ writeAgentTerminalChunk(target.session_id, live)
+ syncAgentTerminalSnapshot(target.session_id, target.output_tail + live)
+ expect(recovered.join('')).toBe(expected + live)
+ expect(neighbor.join('')).toBe(neighborOutput)
+
+ act(() => closeTerminal($activeTerminalId.get()!))
+ const coldReplay = vi.fn()
+ const stopColdProbe = registerAgentTerminalWriter(target.session_id, coldReplay)
+ expect(coldReplay).not.toHaveBeenCalled()
+ stopColdProbe()
+ })
+})
diff --git a/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts b/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
index 45ab443e875..4a0ac2fbed2 100644
--- a/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
+++ b/apps/desktop/src/app/right-sidebar/terminal/use-agent-terminal.ts
@@ -6,9 +6,14 @@ import { useEffect, useRef } from 'react'
import { writeClipboardText } from '@/lib/clipboard'
import { triggerHaptic } from '@/lib/haptics'
+import { $backgroundStatusBySession } from '@/store/composer-status'
import { useTheme } from '@/themes/context'
-import { registerAgentTerminalWriter } from './agent-terminal-stream'
+import {
+ registerAgentTerminalWriter,
+ seedAgentTerminalCommand,
+ syncAgentTerminalSnapshot
+} from './agent-terminal-stream'
import { makeTerminalReader, registerTerminalReader } from './buffer'
import { mirrorSelection, terminalClipboardIntent } from './clipboard'
import { terminalLinkHandler, terminalWebLinksAddon } from './links'
@@ -174,6 +179,17 @@ export function useAgentTerminal({ active, id, procId }: { active: boolean; id:
// Stream live output straight into the terminal (replays backlog on attach).
unregister = registerAgentTerminalWriter(procId, chunk => term.write(chunk))
+ // Closing can evict the backlog while the registry stays unchanged. Pin
+ // the writer before recovering its snapshot so retention cannot evict it.
+ for (const list of Object.values($backgroundStatusBySession.get())) {
+ const item = list.find(item => item.id === procId)
+
+ if (item) {
+ seedAgentTerminalCommand(procId, item.title)
+ syncAgentTerminalSnapshot(procId, item.output ?? '')
+ break
+ }
+ }
unregisterReader = registerTerminalReader(id, makeTerminalReader(term))
}
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 433522bb927..4026e7abbdb 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -1754,6 +1754,15 @@ body.guest-pointer-lock :is(webview, iframe) {
pointer-events: none;
}
+/* Hidden DOM terminals still parse output, but their rows need no layout.
+ Keep the host and xterm helpers measurable for fitting and live font changes;
+ hiding the whole xterm would cache zero-width glyph measurements. WebGL
+ surfaces are deliberately unchanged. */
+[data-terminal].invisible .xterm-rows,
+[data-persistent-terminal][aria-hidden='true'] .xterm-rows {
+ display: none;
+}
+
/* Bottom clearance lives on [data-slot='aui_composer-clearance'] —
virtualized items unmount, so :nth-last-child can't fire reliably. */