feat(desktop): terminal persistence via daemon process#541
Closed
andreasasprou wants to merge 94 commits intosuperset-sh:workspace-sidebarfrom
Closed
feat(desktop): terminal persistence via daemon process#541andreasasprou wants to merge 94 commits intosuperset-sh:workspace-sidebarfrom
andreasasprou wants to merge 94 commits intosuperset-sh:workspace-sidebarfrom
Conversation
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Introduces a workspace-level view mode toggle allowing users to switch between: - **Workbench mode**: Mosaic panes layout with terminals + file viewers for in-flow work - **Review mode**: Dedicated Changes page for focused code review Key changes: - Add ViewModeToggle component in workspace header (prominent segmented control) - Add FileViewerPane with Raw/Rendered/Diff modes, lock/unlock, and split support - Add GroupStrip for group switching above Mosaic content - Unify sidebar to use full ChangesView in both modes (with onFileOpen callback) - Add workspace-view-mode store with per-workspace persistence - Add readWorkingFile tRPC procedure for safe file reads (size/binary checks) - Wire file clicks to open/reuse FileViewer panes (MRU unlocked policy) - Cmd+T in Review mode switches to Workbench first, then creates terminal
- Add !!worktreePath checks to FileViewerPane query enabled conditions - Add !!worktreePath checks to save handler guards (handleSaveRaw, handleSaveDiff) - Fix stale state reference after addTab() in addFileViewerPane action Addresses CodeRabbit review feedback.
… and UX improvements - Add validatePathForWrite() to prevent path traversal attacks in saveFile - Add aria-pressed attribute to ViewModeToggle buttons for accessibility - Increase close button touch target in GroupStrip for better UX - Add .mdx file support for rendered view mode
P0 Security: - Add path validation to getUnstagedVersions before readFile (prevents traversal) - Key Editor/DiffViewer by filePath to force remount (fixes stale Cmd+S closure) P1 Fixes: - Update originalContentRef when raw content loads (dirty tracking fix) - Add .mdx to isMarkdown check for toolbar consistency - Gate diff editable to staged/unstaged only (against-main/committed now read-only) P2 Performance: - Add safeGitShow helper with 2MB size limit on all git show calls - Add size check before reading working tree files in getUnstagedVersions
- P0-1: Add file-viewer type and fileViewer object to paneSchema for tab persistence - P0-2: Fix symlink escape vulnerability in validatePathForWrite by checking if target is symlink and resolving parent directory paths - P1-1: Pass defaultBranch to FileViewerPane for against-main diffs - P1-2: Switch staged diff to unstaged after save (matches Review mode behavior) - P2: Use Buffer.byteLength instead of string.length in safeGitShow for accurate UTF-8 byte counting
P0 (critical):
- Remove duplicate saveFile from git-operations.ts that was overwriting
the hardened version in file-contents.ts (security vulnerability)
P1 (must fix):
- Use basename()/dirname() from node:path instead of split('/') for
cross-platform Windows compatibility in validatePathForWrite
- Add preflight size check with git cat-file -s in safeGitShow to
prevent memory spikes from large blobs before materializing content
P2 (UX):
- Fix split pane to clone file-viewer state instead of creating terminal
when splitting a file-viewer pane (locked by default)
Question fix:
- Show GroupStrip with add button even when tabs.length === 0 so users
have visible UI to create new terminal (not just hotkey)
…ocalDb
P0 (CRITICAL SECURITY):
- Add validateWorktreePathInDb() that verifies worktreePath exists in
localDb.worktrees before any filesystem operations
- Without this, a compromised renderer could read/write arbitrary files
by passing worktreePath='/' and filePath='.ssh/id_rsa'
- Applied to getFileContents, saveFile, and readWorkingFile procedures
P1 (correctness):
- Replace startsWith('..') checks with segment-aware containsPathTraversal()
and isPathOutsideBase() helpers that use path.sep
- Fixes false positives on valid paths like '..foo/bar' (directories
starting with '..')
- Cross-platform compatible (handles both / and \ separators)
P2 (performance):
- Guard killTerminalForPane() calls on pane.type === 'terminal'
- Prevents unnecessary IPC and warning logs when closing file-viewer panes
…ve editor drafts P0 (security): - Extract assertWorktreePathInDb to shared security.ts - Returns worktree record to avoid duplicate queries - Apply validation to ALL routes: git-operations, status, staging, branches P1 (data loss): - Preserve unsaved editor content across view mode switches - Store draft in ref before switching away from raw mode - Restore draft when returning to raw mode - Clear draft on save and file change - Update dirty state on editor mount with draft content
…otection P0 Security (BLOCK): - Add validatePathInWorktree() check before rm() in deleteUntracked - Prevents path traversal (../) and symlink escape attacks - Consolidated path validation utilities in security.ts P1 Data Loss: - Track save source (Raw vs Diff) with savingFromRawRef - Only clear draft when saving from Raw mode - Disable Diff editing when Raw draft exists (forces user to save/discard) P2: - Use ['--', filePath] in git.add() to handle paths starting with -
…th validation - Reduce security.ts from 213 to 65 lines - Remove async symlink/realpath checking (users own their repos) - Remove segment-aware path traversal (..foo edge case not worth complexity) - Keep worktreePath DB validation (the real security boundary) - Keep simple .. and absolute path checks (sufficient for 99.99% of cases)
P0 (blocking): - Add path validation (rejects .. and absolute) to applyUntrackedLineCount - Add 1MB size cap to prevent OOM on large untracked files during polling P2: - Add type guard in updateTabLayout - only call killTerminalForPane for terminal panes - Use ['--', branch] in switchBranch to ensure branch treated as refname
…lidation - Add path-validation.ts with industry-standard containment check (path.relative) - Add secure-fs.ts with self-validating FS wrappers (symlink escape protection) - Add git-commands.ts with semantic helpers (gitSwitchBranch vs gitCheckoutFile) - Fix switchBranch: use 'git switch' instead of 'git checkout --' (was file checkout) - Fix path traversal check: segment-aware (allows ..foo, rejects ..) - Fix symlink bypass: check parent dirs for new files, use stat not lstat - Fix worktree root deletion: explicit allowRoot check - All FS operations now go through secureFs with validation built-in
Add a setting to control whether Cmd+clicking file paths in the terminal opens them in an external editor (default) or in the in-app FileViewerPane. - Add terminalLinkBehavior setting to local-db schema with migration - Add getTerminalLinkBehavior/setTerminalLinkBehavior tRPC procedures - Refactor createTerminalInstance to accept onFileLinkClick callback - Wire up setting in Terminal.tsx with ref pattern (avoids terminal recreation) - Add Select UI in BehaviorSettings for choosing link behavior
Remove async symlink escape detection from path validation since the threat model doesn't justify it: a compromised renderer already has terminal access for arbitrary command execution. Changes: - Replace resolveSecurePath (async) with resolvePathInWorktree (sync) - Remove assertNoSymlinkEscape and checkSymlinks option - Add validateRelativePath for simple path safety checks - Update secure-fs.ts to use new sync functions - Update threat model documentation in path-validation.ts
…s sidebar) Add a setting to let users choose between displaying workspaces as horizontal tabs in the TopBar (current behavior) or in a dedicated left sidebar (new feature, similar to Linear/GitHub Desktop). Key changes: - Add navigationStyle column to settings table (migration 0005) - Add navigation style dropdown in Behavior Settings - Create WorkspaceSidebar component with collapsible project sections - Create shared useWorkspaceShortcuts hook (⌘1-9 shortcuts, auto-create) - Update TopBar to conditionally render based on navigation style - Add ⌘⇧B hotkey to toggle workspace sidebar 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ition P0: Add CreateWorkspaceButton to TopBar when in sidebar mode - Button was previously only rendered via WorkspaceTabs - Now renders in top-right section when navigationStyle is sidebar P1: Fix race condition in createBranchWorkspace - Add unique partial index on (projectId) WHERE type='branch' - Use INSERT ON CONFLICT DO NOTHING to handle concurrent calls - If conflict, fetch the existing workspace instead of failing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
WorkspaceListItem now has full feature parity: - Close/delete button with confirmation dialog - Context menu (Rename, Open in Finder) - Hover card with PR details, checks, reviews - Needs attention indicator (red pulse) - Inline rename (double-click) - Drag & drop reordering - BranchSwitcher for branch workspaces Other changes: - Remove CreateWorkspaceButton from TopBar in sidebar mode - Add per-project "Add workspace" dropdown (New Workspace, Quick Create) - Add preSelectedProjectId to modal store for pre-selecting project - Simplify GroupStrip to use consistent browser-tab style 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Extract useWorkspaceDeleteHandler hook for shared delete logic - Use existing extractPaneIdsFromLayout from tabs/utils instead of inline collectPaneIds - Add named constants for magic numbers (staleTime, delays, shortcut index) - Reduces code duplication between WorkspaceItem and WorkspaceListItem 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ar mode Move SidebarControl to shared location (screens/main/components/) and conditionally render based on navigation style: - top-bar mode: toggle in TopBar (unchanged) - sidebar mode: toggle in WorkspaceActionBar (left side, before branch info) This improves UX by placing the sidebar toggle closer to the content it controls when in sidebar navigation mode.
Default to Mac layout (80px padding) while platform query is loading, since undefined === 'darwin' evaluates to false, causing 16px padding to be used initially on Mac before the query resolves.
…minal links P0: Fix branch workspace support in assertRegisteredWorktree - Extended validation to check both worktrees.path AND projects.mainRepoPath - Branch workspaces use mainRepoPath which wasn't being validated P1: Fix terminal file-viewer links for absolute paths - Normalize absolute paths to worktree-relative before opening file viewer - File viewer expects relative paths but terminal links can be absolute P2: Fix misleading security comments - Removed claims about symlink checks that aren't implemented - Comments now accurately describe worktree registration + path traversal validation
- Add markWorkspaceAsUnread action to tabs store that sets needsAttention=true for all panes in a workspace - Add context menu item with LuEyeOff icon to: - WorkspaceItemContextMenu (top bar tabs) - WorkspaceListItem (sidebar) for both branch and worktree workspaces - Leverages existing needsAttention indicator system (red pulsing dot) - Logs when no panes exist in workspace (empty workspace edge case)
Previously, clicking a workspace only set it as active but didn't clear the needsAttention state on panes. This meant 'Mark as Unread' worked but clicking the workspace didn't mark it as read. Added clearWorkspaceAttention action that clears needsAttention for all panes in a workspace, called when clicking workspace in both top bar and sidebar.
P0: Make unique branch workspace migration resilient to existing duplicates - Dedupe existing duplicate branch workspaces before creating unique index - Update settings.last_active_workspace_id if it points to deleted workspace P1: Fix isResizing persistence and store selector usage - Exclude ephemeral isResizing from Zustand persistence via partialize - Use selector pattern in MainScreen to avoid unnecessary re-renders P1: Fix delete handler to show dialog when canDeleteData is undefined - Safe default: show confirmation when query fails P2: Fix path boundary check in terminal file links - Use path.startsWith(cwd + '/') to avoid false prefix matches P2: Add missing drizzle migration snapshot - Created 0006_snapshot.json for consistency
P0: Add symlink escape protection for File Viewer writes - Block writes if file's realpath escapes worktree boundary - Add isSymlinkEscaping() method for UI to detect and warn users - Update threat model docs to reflect new symlink protection P1: Fix race condition in createBranchWorkspace ordering - Insert workspace first, then shift others only on success - Losers of the race no longer corrupt tabOrder - Exclude newly inserted workspace from shift operation P2: Fix migration to keep most recently used duplicate - Select survivor by last_opened_at DESC (not arbitrary MIN(id)) - Use id ASC as tiebreaker when last_opened_at is equal
Consolidate two navigation bars into a single unified top bar: - Create WorkspaceControls component group in TopBar/ - BranchIndicator: shows current branch (keyboard-focusable) - OpenInMenuButton: compact Open button with dropdown - ViewModeToggleCompact: Workbench/Review toggle (24px height) - Remove WorkspaceActionBar from WorkspaceView entirely - Delete unused WorkspaceActionBar component folder Improvements based on Oracle review: - Optimize Zustand selector to minimize rerenders - Add toast error handling for open/copy mutations - Add path to Open button tooltip for discoverability - Add focus-visible rings for keyboard accessibility - Use text-xs for consistent typography Also includes minor lint auto-fixes (import sorting, template literals)
- Simplify useWorkspaceDeleteHandler to always show dialog instead of auto-deleting clean workspaces - Update tooltip from 'Delete workspace' to 'Close or delete' for clarity - Add isUnread state for workspace unread tracking - Add workspace setUnread mutation and schema migration
- Clear xterm-webgl texture atlas after rehydration to force a clean repaint - Add a first-render fallback so restored sessions can't get stuck not-ready - Surface terminal stream error events
- Run PTYs in per-session subprocesses and frame IO as binary - Time-slice headless emulator output processing to keep daemon responsive - Handle PTY input backpressure (EAGAIN/EWOULDBLOCK) without dropping chunks - Improve renderer paste handling (bracketed paste + chunking) and surface errors
- Track async GPU renderer via ref to reliably clear WebGL atlas - Schedule fit+refresh on focus/resize to avoid partial renders when switching panes
Avoid fit/PTY resizes and WebGL atlas clears on focus; do a lightweight refresh instead.
- Remove duplicate terminalError handler in daemon-manager.ts (was causing duplicate event emissions) - Fix failing write test in manager.test.ts (add async wait for PtyWriteQueue flush before assertion) - Fix attach() hang with continuous output in session.ts (add 500ms timeout to flushEmulatorWrites to prevent indefinite hang when processes like tail -f produce continuous output) - Apply biome formatting fixes
Retry focus redraw until container has non-zero size to avoid WebGL glitches on tab switches.
- Default xterm renderer to Canvas on macOS to avoid WebGL corruption on tab switches - Remove focus redraw hacks that were amplifying WebGL glitches
- Fix initialCommands race: use waitForReady() instead of setTimeout(100) - Add PTY ready promise in session to signal when subprocess spawned - Add queue limits for both subprocess stdin and client notify queues - Emit terminalError when writeNoAck drops input due to full queue - Complete detachAllListeners: add disconnect: and error: prefixes - Shutdown orphaned daemon when persistence disabled on app startup
- Extract magic number to SESSION_CLEANUP_DELAY_MS constant in daemon-manager - Move planning docs to docs/ directory - Extract useTerminalConnection hook to encapsulate tRPC mutations and refs - Refactor Terminal.tsx to use the new hook, reducing component complexity
…tence disabled Previously, shutdownOrphanedDaemon() would call client.shutdown() which internally calls ensureConnected(), spawning a new daemon just to immediately shut it down. This happened on every app startup when terminal persistence was disabled. Added tryConnectAndAuthenticate() and shutdownIfRunning() methods to TerminalHostClient that only attempt cleanup if a daemon is already running, avoiding wasteful spawn+kill cycles.
- Reframe PtyWriteQueue docstring to accurately describe limitations (reduces event loop starvation, does not prevent blocking) - Rename prototype/ to __tests__/ for conventional test organization
For TUI sessions (alternate screen mode), serialized snapshots render incorrectly due to styled spaces and positioning issues. Instead of trying to perfectly serialize and restore TUI state, we now: 1. Skip writing the broken snapshot for alt-screen sessions 2. Enter alt-screen mode directly 3. Enable streaming first so live PTY output comes through 4. Trigger SIGWINCH via resize down/up - TUI redraws itself Trade-off: Brief visual flash as TUI redraws, but the result is correct. Normal shell sessions still use the snapshot approach which works well. - Add SIGWINCH-based redraw for TUI (alt-screen) session reattach - Remove dead resize nudge code (now handled by SIGWINCH approach) - Clean up verbose debug logging from investigation - Update research doc with final fix documentation - Add snapshot boundary tracking for consistent daemon-side captures
…allback The fallback logic for detecting alternate screen mode was using presence/absence checks (includes) instead of position comparison (lastIndexOf). This caused incorrect detection when a user entered and exited alternate screen multiple times (e.g., opened vim, closed it, opened it again). Changed to use lastIndexOf comparison, matching the pattern already used in updateModesFromData and for bracketed paste detection. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Merge 3 separate documentation files into a single comprehensive reference: - TERMINAL_RENDERING_REATTACH_RESEARCH.md (research log) - 20251229-terminal-host-daemon-terminal-persistence.md (exec plan) - LARGE_PASTE_HANG_ANALYSIS.md (bug analysis) New file uses date prefix for chronological sorting.
- Add escalation watchdog in handleKill: SIGTERM → SIGKILL → force exit node-pty's onExit callback doesn't fire reliably after pty.kill(SIGTERM) - Fix dispose() async bug: capture subprocess ref before nullifying - Add diagnostic logging throughout kill flow for debugging - Fix Terminal.tsx hook dependency warnings with targeted biome-ignore - Add TERMINAL_HOST_RUNBOOK.md for daemon debugging/testing
Keep essential warnings (force exit, attach timeout, force dispose stuck session). Remove step-by-step debugging logs that are too noisy for production.
…kspace switch When terminal persistence is enabled, render all tabs from all workspaces and use visibility:hidden for inactive ones. This eliminates the unmount/remount cycle that caused race conditions during TUI reattach. Changes: - TabsContent: query terminalPersistence setting, render all tabs when enabled - TerminalSettings: add memory warning copy - Terminal.tsx: remove debug logging, add comments clarifying SIGWINCH as fallback - Technical notes: document the approach and trade-offs
In daemon mode, both scrollback and snapshot.snapshotAnsi contained identical ANSI content, doubling IPC payload size (~500KB → 1MB). Changes: - daemon-manager: set scrollback to empty string in daemon mode - Terminal.tsx: use initialAnsi variable preferring snapshot.snapshotAnsi - Terminal.tsx: use snapshot.cwd directly instead of parsing ANSI - Terminal.tsx: only run escape scanning when snapshot.modes unavailable - types.ts: add JSDoc clarifying daemon mode behavior ~50% reduction in IPC payload for terminal sessions.
- Remove unused ptyPid property from Session - Remove unused flushEmulatorWrites method (superseded by flushEmulatorWritesUpTo) - Remove unused getSession method (superseded by getActiveSession) - Fix template literal style in Terminal.tsx - Fix export ordering in hooks/index.ts
Preserves terminal scrollback across daemon restarts/reboots. When app restarts without a running daemon, previous session output is restored with a full-screen overlay prompting user to start a new shell.
andreasasprou
force-pushed
the
persistent-terminals
branch
from
cfdfe5d to
e72ea41
Compare
andreasasprou
added a commit
to andreasasprou/superset
that referenced
this pull request
Jan 3, 2026
Includes: - feat(desktop): add 3-color workspace status indicators - feat(desktop): terminal persistence via daemon process (stacked from superset-sh#541) - refactor(desktop): extract StatusIndicator shared component - Multiple security and UX fixes Conflicts resolved: - apps/desktop/src/main/terminal-host/session.ts: duplicate ptyPid property declaration
andreasasprou
force-pushed
the
workspace-sidebar
branch
from
edc4dae to
7e9a724
Compare
Contributor
Author
|
Recreating PR from upstream branch (superset-sh:persistent-terminals) instead of fork |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
[Internal] Bugs to fix pre-merge
shortcuts (like CMD+W) don't work when focusing on the terminal content
Root cause & proposed fix (click to expand)
Root cause: Event propagation failure between xterm.js and react-hotkeys-hook.
When xterm's
attachCustomKeyEventHandlerreturnsfalse:useHotkeys("CLOSE_TERMINAL", ...)in WorkspaceView never receives the eventProposed fix (follow-up PR): Blended approach with two tiers:
CLOSE_TERMINAL): Always dispatch to document - "owned" by SupersetFiles to modify:
helpers.ts(add priority hotkeys logic),Terminal.tsx(passisInAlternateScreencallback)Summary
This PR adds terminal session persistence via a background daemon process that survives app restarts.
Closes #518 (supersedes the tmux-based approach with a Superset-owned daemon)
Details
Architecture
How it works
SUPERSET_TERMINAL_DAEMON=1env var)Why daemon instead of tmux
New Features
Settings UI Toggle
SUPERSET_TERMINAL_DAEMON=1still works as override for developmentTUI Mode Rehydration
Smooth Workspace/Tab Switching
visibility: hiddento hide inactive terminals while preserving xterm stateLarge Paste Reliability (vi)
virepaintsEAGAIN/EWOULDBLOCK) is retried with backoff (no dropped chunks)Manual Test Checklist
Core Functionality
ls -la,echo hello) → Quit app → Reopen → Scrollback preservedhttps://www.loom.com/share/cf528b13c50c4e37869a851fdc5e89db
https://www.loom.com/share/56cb665c008844538646f19f2fa7b66a
htop,vim, orless→ Quit app → Reopen → TUI restores correctly (alternate screen mode)https://www.loom.com/share/6dc8ec076f9f4afe85049b5eea73b831
Daemon Lifecycle
Daemon Restart (Settings)- Removed for v1 (see Known Limitations)pkill -f terminal-host→ Daemon respawns on next terminal operationps aux | grep terminal-host→ Daemon still runningError Handling
Connection Timeout: If daemon is unresponsive, error UI appears within ~10 seconds (not infinite hang)
Retry Button: Error overlay "Retry Connection" button successfully reconnects
Workspace Management
Edge Cases
find /) → Quit → Reopen → Full scrollback preservedhttps://www.loom.com/share/9822c91f288549ba8311da960144bdac
sleep 1000) → Quit → Reopen → Process still running in restored terminalvi→ No freezes and paste completes (tested with ~3k lines)Production Build
bun run build) → Test all above in.appbundle~/.superset/terminal-host.*files → Launch app → Daemon spawns correctlyBasic Test Plan (Quick Validation)
claudeoropencode)ps aux | grep terminal-hostKnown Limitations
Protocol version strictness — Strict equality check on protocol version may break "survive app updates" promise if version is ever bumped. Consider semantic versioning or graceful degradation.
No daemon restart UI — For v1, if the daemon becomes unresponsive, users can manually kill it:
pkill -f terminal-host. The daemon will respawn automatically on next terminal operation. If users report frequent daemon issues, implement auto-recovery (health check + automatic restart) in v2.Memory usage with many terminals — When persistence is enabled, all terminals stay mounted across workspace switches. This may increase memory usage for users with many terminals/workspaces. Settings page includes warning copy. Users can disable persistence if they notice performance issues.
Future Improvements
These are documented in
apps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.md:Buffer PTY output for hidden terminals — Pause xterm.write() when a terminal's tab is hidden; replay buffer on reactivation. Reduces CPU for inactive terminals.
LRU terminal hibernation — If memory pressure detected, dispose oldest inactive xterm instances and rely on SIGWINCH restoration when user returns. Balances memory vs smooth switching.
Reduce scrollback for hidden terminals — Temporarily shrink scrollback buffer for hidden terminals; restore on activation.
Memory usage telemetry — Add metrics to understand real-world memory patterns (terminals per workspace, scrollback sizes, etc.) to inform future optimizations.
Technical Notes
TUI Restoration via SIGWINCH
TUI apps (alternate screen mode) are restored using a SIGWINCH-based redraw approach instead of snapshot serialization:
Trade-off: Brief visual flash as TUI redraws, but the result is always correct. The TUI is the authority on its own display—we just trigger a refresh.
Why snapshots don't work for TUIs: TUIs use styled spaces (spaces with background colors) to create panels and borders. SerializeAddon captures buffer cell content, but serialization of styled empty cells is inconsistent. When restored, the snapshot renders sparsely—missing panels, borders, and UI chrome.
Note: With "keep terminals mounted" enabled, the SIGWINCH path is primarily a fallback for app restart recovery. During normal workspace/tab switching, terminals stay mounted and no reattach is needed.
Keep Terminals Mounted
To eliminate white screen issues during workspace/tab switching, we keep all terminal xterm.js instances mounted when persistence is enabled:
TabsContentrenders all tabs from all workspacesvisibility: hidden; pointer-events: nonevisibility: visible; pointer-events: autoWhy
visibility: hidden: Unlikedisplay: none, it preserves element dimensions. xterm.js and FitAddon require non-zero dimensions to function correctly.Trade-off: Higher memory usage with many terminals. The SIGWINCH restoration logic remains as a fallback for app restart recovery.
See
apps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.mdfor detailed analysis.Bug Fixes in This PR
TUI White Screen on Workspace Switch (FIXED)
Problem: Switching between workspaces with TUI apps running (vim, opencode, claude) caused white/blank screens. Manual window resize would fix it.
Root Cause: React unmounts the Terminal component on workspace switch, destroying the xterm.js instance. On return, a new xterm instance must be created and reattached to the PTY session. Despite correct SIGWINCH timing, race conditions between xterm initialization and PTY output caused blank screens. The fundamental issue is that xterm.js emulator state is lost on unmount.
Fix: Keep all terminal xterm.js instances mounted when persistence is enabled:
TabsContentvisibility: hiddenfor inactive terminalsTrade-off: Higher memory usage with many terminals. Settings page includes warning copy.
TUI Corruption on Tab Switch (e.g., opencode, vim)
Problem: Switching away from a terminal running a TUI and switching back resulted in visual corruption—missing ASCII art, input boxes, and UI elements.
Root Cause: Serialized snapshots don't capture TUI state correctly. TUIs use styled spaces (spaces with background colors) for panels and borders, and these serialize inconsistently.
Fix: For alt-screen (TUI) sessions, skip the broken snapshot and trigger SIGWINCH instead:
Trade-off: Brief flash as TUI redraws, but always renders correctly.
xterm "dimensions" Error (Tab Switching)
Problem: Switching between terminal tabs caused
Cannot read properties of undefined (reading 'dimensions')error, breaking keyboard input.Root Cause:
xterm.open()schedules internal timeouts. Ifxterm.dispose()runs before those timeouts fire, it crashes.Fix:
xterm.dispose()withsetTimeout(0)to let internal xterm.js timeouts completependingDetachesMap for React StrictMode debouncingReact StrictMode Double-Mount
Problem: In dev mode, terminals couldn't accept input after tab switch.
Root Cause: StrictMode runs effects twice (mount→unmount→mount). The detach on first unmount corrupted state.
Fix: Module-level
pendingDetachesMap that cancels pending detaches when component remounts.Large Paste into
vi(hangs / dropped chunks)Problem: Pasting large blocks of text into
vicould freeze the daemon (all terminals) or stop mid-paste with missing chunks.Root Cause: Combination of CPU-bound output processing during
virepaints and missing backpressure handling for PTY input (non-blocking fd writes returningEAGAIN/EWOULDBLOCK).Fix:
EAGAIN/EWOULDBLOCKwith backoff; pause/resume on backlogWebGL Render Corruption on macOS (Tab Switching)
Problem: Severe corruption/glitching when switching between terminals on macOS with
xterm-webgl.Root Cause: xterm-webgl has rendering issues on macOS when terminals are hidden/shown or switched between panes.
Fix: Default to Canvas renderer on macOS for stability. WebGL is still used on other platforms.
To force a renderer for testing:
localStorage.setItem('terminal-renderer', 'webgl' | 'canvas' | 'dom'), then reload.--disable-gpuremains a useful diagnostic if WebGL is forced.Example of the corruption (before fix):
Status
Files Changed
New Files
apps/desktop/src/main/terminal-host/— Daemon process (7 files:index.ts,terminal-host.ts,session.ts,pty-subprocess.ts,pty-subprocess-ipc.ts, + tests)apps/desktop/src/main/lib/terminal-host/— Client library (client.ts,headless-emulator.ts,types.ts, + tests)apps/desktop/src/main/lib/terminal/daemon-manager.ts— DaemonTerminalManagerapps/desktop/src/main/lib/terminal/pty-write-queue.ts— Input backpressure handlingapps/desktop/src/renderer/.../SettingsView/TerminalSettings.tsx— Settings UIapps/desktop/src/renderer/.../Terminal/hooks/useTerminalConnection.ts— Connection hookpackages/local-db/drizzle/0004_add_terminal_persistence_setting.sql— Migrationapps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.md— Technical notes (consolidated)Modified Files
apps/desktop/src/main/lib/terminal/index.ts—isDaemonModeEnabledreads from settingsapps/desktop/src/main/lib/terminal/session.ts— PTY session managementapps/desktop/src/main/lib/terminal/manager.ts— Terminal manager with daemon supportapps/desktop/src/main/lib/terminal/types.ts— Terminal type definitionsapps/desktop/src/main/lib/terminal/port-manager.ts— Port detectionapps/desktop/src/renderer/.../Terminal/Terminal.tsx— SIGWINCH TUI restore, error UI, StrictMode fix, IPC payload optimizationapps/desktop/src/renderer/.../Terminal/helpers.ts— Deferred GPU renderer, Canvas default on macOSapps/desktop/src/renderer/.../Terminal/types.ts— Stream event typesapps/desktop/src/renderer/.../TabsContent/index.tsx— Keep terminals mounted when persistence enabledapps/desktop/src/renderer/stores/app-state.ts— App state updatesapps/desktop/src/lib/trpc/routers/settings/index.ts— Terminal persistence setting endpointsapps/desktop/src/lib/trpc/routers/terminal/terminal.ts— Terminal router updatesapps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts— Workspace cleanup integrationapps/desktop/src/lib/trpc/routers/projects/projects.ts— Project cleanup integrationapps/desktop/src/main/index.ts— Daemon lifecycle managementapps/desktop/src/main/windows/main.ts— Window integrationapps/desktop/electron.vite.config.ts— Build config updatesapps/desktop/package.json— Dependenciespackages/local-db/src/schema/schema.ts— Settings schemaSettingsContent.tsx,GeneralSettings.tsx) — Terminal section in sidebar