diff --git a/apps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.md b/apps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.md
new file mode 100644
index 00000000000..9b7bf2ff3da
--- /dev/null
+++ b/apps/desktop/docs/2026-01-02-terminal-persistence-technical-notes.md
@@ -0,0 +1,335 @@
+# Terminal Persistence — Technical Notes
+
+> **Date**: January 2026  
+> **Feature**: Terminal session persistence via daemon process  
+> **PR**: #541
+
+This document captures the technical decisions, debugging investigations, and solutions for the terminal persistence feature. It's intended for engineers who need to understand **why** certain approaches were chosen.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [TUI Restoration: Why SIGWINCH Instead of Snapshots](#tui-restoration-why-sigwinch-instead-of-snapshots)
+3. [Keeping Terminals Mounted Across Workspace Switches](#keeping-terminals-mounted-across-workspace-switches)
+4. [Large Paste Reliability: Subprocess Isolation + Backpressure](#large-paste-reliability-subprocess-isolation--backpressure)
+5. [Renderer Notes: WebGL vs Canvas on macOS](#renderer-notes-webgl-vs-canvas-on-macos)
+6. [Design Options Considered](#design-options-considered)
+7. [Future Improvements](#future-improvements)
+8. [Reference Links](#reference-links)
+
+---
+
+## Architecture Overview
+
+High-level data flow:
+
+```
+Renderer (xterm.js in React)
+  ↕ TRPC stream/write calls
+Electron main
+  ↕ Unix socket IPC
+terminal-host daemon (Node.js)
+  ↕ stdin/stdout IPC (binary framing)
+per-session PTY subprocess (Node.js + node-pty)
+  ↕ PTY
+shell / TUI (opencode, vim, etc.)
+```
+
+Key concepts:
+
+- **Daemon owns sessions** so terminals persist across app restarts.
+- **Headless emulator** in daemon maintains a model of the terminal state (screen + modes) and produces a snapshot for reattach.
+- **Per-session subprocess** isolates each PTY so one terminal can't freeze others.
+- **Renderer is recreated** on React mount; on "switch away" we detach and later reattach to the daemon session.
+
+---
+
+## TUI Restoration: Why SIGWINCH Instead of Snapshots
+
+### The Problem
+
+When switching away from a terminal running a TUI (like opencode, vim, claude) and switching back, we saw visual corruption—missing ASCII art, input boxes, and UI elements.
+
+### Why Snapshots Don't Work for TUIs
+
+1. TUIs use "styled spaces" (spaces with background colors) to create UI elements
+2. `SerializeAddon` captures buffer cell content, but serialization of styled empty cells is inconsistent
+3. When restored, the serialized snapshot renders sparsely—missing panels, borders, and UI chrome
+
+**Diagnostic data showed the problem:**
+```
+ALT-BUFFER: lines=52 nonEmpty=14 chars=2156
+```
+A full TUI screen (91×52 = 4732 cells) should have far more content. The alt buffer was sparse.
+
+### Investigation Timeline
+
+| # | Hypothesis | Test | Result |
+|---|------------|------|--------|
+| 1 | Live events interleaving with snapshot | Added logging for pending events | ❌ PENDING_EVENTS=0 |
+| 2 | Double alt-screen entry | Disabled manual entry | ❌ Still corrupted |
+| 3 | WebGL renderer issues | Forced Canvas renderer | ❌ Still corrupted |
+| 4 | Dimension mismatch | Logged xterm vs snapshot dims | ❌ MATCH=true |
+| 5 | Alt-screen buffer mismatch | Logged transition sequences | ❌ CONSISTENT=true |
+
+### Root Cause: Flush Timeout During Snapshot
+
+**Location:** `Session.attach()` in `apps/desktop/src/main/terminal-host/session.ts`
+
+With continuous TUI output (like OpenCode), the emulator write queue NEVER empties in the timeout window. `Promise.race()` times out, but queued data never made it to xterm before snapshot capture.
+
+### The Solution: Skip Snapshot, Trigger SIGWINCH
+
+Instead of trying to perfectly serialize and restore TUI state:
+
+1. **Skip writing the broken snapshot** for alt-screen (TUI) sessions
+2. **Enter alt-screen mode** directly so TUI output goes to the correct buffer
+3. **Enable streaming first** so live PTY output comes through
+4. **Trigger SIGWINCH** via resize down/up—TUI redraws itself from scratch
+
+```typescript
+if (isAltScreenReattach) {
+  xterm.write("\x1b[?1049h");  // Enter alt-screen
+  isStreamReadyRef.current = true;
+  flushPendingEvents();
+  
+  // Trigger SIGWINCH via resize
+  resizeRef.current({ paneId, cols, rows: rows - 1 });
+  setTimeout(() => {
+    resizeRef.current({ paneId, cols, rows });
+  }, 100);
+}
+```
+
+### Trade-offs
+
+| Aspect | Snapshot Approach | SIGWINCH Approach |
+|--------|-------------------|-------------------|
+| Visual continuity | Broken (sparse/corrupted) | Brief flash as TUI redraws |
+| Correctness | Unreliable | Reliable (TUI owns its state) |
+| Complexity | High | Low |
+
+**Non-TUI sessions** (normal shells) still use the snapshot approach, which works correctly for scrollback history and shell prompts.
+
+---
+
+## Keeping Terminals Mounted Across Workspace Switches
+
+### The Problem
+
+Even with SIGWINCH-based TUI restoration working correctly, switching between workspaces still caused intermittent white screen issues for TUI apps. Manual window resize would fix it, but the experience was jarring.
+
+**Root cause:** When switching workspaces, React unmounts the `Terminal` component entirely, destroying the xterm.js instance. On return, a new xterm instance must be created and reattached to the existing PTY session. Despite correct SIGWINCH timing, race conditions between xterm initialization and PTY output caused blank/white screens.
+
+### The Solution: Keep All Terminals Mounted
+
+Instead of unmounting Terminal components on workspace/tab switch:
+
+1. **Render all tabs from all workspaces** simultaneously in `TabsContent`
+2. **Hide inactive tabs with CSS** (`visibility: hidden; pointer-events: none;`)
+3. **Show only the active tab** for the active workspace
+
+**Implementation:** `TabsContent/index.tsx` renders `allTabs` with visibility toggling instead of conditional rendering.
+
+### Why `visibility: hidden` Instead of `display: none`
+
+Using `visibility: hidden` (not `display: none`) is critical:
+- `display: none` removes the element from layout, giving it 0×0 dimensions
+- xterm.js and FitAddon expect non-zero dimensions to function correctly
+- `visibility: hidden` preserves the element's layout dimensions while hiding it visually
+
+### Why This Works
+
+- xterm.js instances persist across navigation—no recreation needed
+- No state reconstruction, no reattach timing issues
+- The terminal stays exactly as it was when hidden
+- The complex SIGWINCH/snapshot restoration code becomes a fallback path only (used for app restart recovery)
+
+### Trade-offs
+
+| Aspect | Impact | Mitigation |
+|--------|--------|------------|
+| Memory | Each terminal holds scrollback buffer + xterm render state | See Future Improvements: LRU hibernation |
+| CPU | Hidden terminals still process PTY output | See Future Improvements: buffer output |
+| DOM nodes | Many elements even when hidden | `visibility: hidden` is cheap; browser optimizes |
+
+### When This Applies
+
+This optimization is **only enabled when Terminal Persistence is ON** in Settings. When persistence is disabled, the original behavior (unmount on switch) is used.
+
+### Fallback Path
+
+The SIGWINCH-based restoration logic remains in `Terminal.tsx` as a fallback for:
+- **App restart recovery** — fresh xterm must reattach to daemon's PTY session
+- **Edge cases** — any scenario where the Terminal component truly remounts
+
+---
+
+## Large Paste Reliability: Subprocess Isolation + Backpressure
+
+### The Problem
+
+Pasting large blocks of text (e.g. 3k+ lines) into `vi` could:
+- Hang the terminal daemon / freeze all terminals, or
+- Partially paste and then silently stop (missing chunks)
+
+Most visible on macOS (small kernel PTY buffer + very high output volume during `vi` repaints).
+
+### Two Distinct Failure Modes
+
+**1) CPU saturation on output (daemon side)**
+
+Large pastes cause `vi` to repaint aggressively, producing huge volumes of escape-sequence-heavy output. If the daemon tries to parse that output in large unbounded chunks, it monopolizes the event loop.
+
+**2) Backpressure on input (PTY write side)**
+
+PTY writes must respect backpressure. When writing to a PTY fd in non-blocking mode, the kernel can return `EAGAIN`/`EWOULDBLOCK`. If treated as fatal, paste chunks get dropped.
+
+### The Solution
+
+**Process isolation (per terminal)**
+
+Each PTY runs in its own subprocess (`pty-subprocess.ts`). One terminal hitting backpressure can't freeze the daemon or other terminals.
+
+**Binary framing (no JSON on hot paths)**
+
+Subprocess ↔ daemon communication uses length-prefixed binary framing (`pty-subprocess-ipc.ts`) to avoid JSON overhead on escape-heavy output.
+
+**Output batching + stdout backpressure**
+
+Subprocess batches PTY output (32ms cadence, 128KB max) and pauses PTY reads when `process.stdout` is backpressured.
+
+**Input backpressure (retry, don't drop)**
+
+Subprocess treats `EAGAIN`/`EWOULDBLOCK` as expected backpressure:
+- Keeps queued buffers
+- Retries with exponential backoff (2ms → 50ms)
+- Pauses upstream when backlog exceeds high watermark
+
+**Daemon responsiveness (time-sliced emulator)**
+
+The daemon applies PTY output to the headless emulator in time-budgeted slices.
+
+### Debugging
+
+Set these env vars and restart the app:
+- `SUPERSET_PTY_SUBPROCESS_DEBUG=1` — subprocess batching + PTY input backpressure logs
+- `SUPERSET_TERMINAL_EMULATOR_DEBUG=1` — daemon emulator budget/overrun logs
+
+```bash
+ps aux | rg "terminal-host|pty-subprocess"
+```
+
+---
+
+## Renderer Notes: WebGL vs Canvas on macOS
+
+### The Problem
+
+Severe corruption/glitching when switching between terminals on macOS with `xterm-webgl`.
+
+### Current Approach
+
+- **Default to Canvas on macOS** for stability
+- **WebGL on other platforms** for performance
+- Allow override for testing via localStorage:
+  ```javascript
+  localStorage.setItem('terminal-renderer', 'webgl' | 'canvas' | 'dom')
+  localStorage.removeItem('terminal-renderer')  // revert to default
+  ```
+
+### Why Warp Feels Smoother
+
+Warp's architecture is GPU-first (Metal on macOS) with careful minimization of bottlenecks. That doesn't automatically mean "WebGL fixes it" inside xterm.js—in practice `xterm-webgl` has had regressions on macOS.
+
+---
+
+## Design Options Considered
+
+These were evaluated during the design phase:
+
+### Option A — Don't detach on tab switch (keep renderer alive)
+
+Make tab switching purely a show/hide operation. Removes the core "reattach baseline mismatch" failure mode.
+
+**Pros:** Fastest path to eliminating corruption  
+**Cons:** More memory if many terminals open; needs hibernation policies
+
+### Option B — tmux-style server authoritative screen diff
+
+Daemon maintains full screen grid; sends diffs to clients.
+
+**Pros:** Robust reattach  
+**Cons:** Significant engineering effort; essentially building a multiplexer
+
+### Option C — Use tmux/screen as persistence layer
+
+Put tmux behind the scenes.
+
+**Pros:** tmux already solved this  
+**Cons:** External dependency; platform concerns
+
+### Option D — Per-terminal WebContents/BrowserView
+
+Host each terminal in a persistent Electron view.
+
+**Pros:** Avoid rehydrate for navigation  
+**Cons:** Complex Electron lifecycle
+
+### What We Chose
+
+For v1, we implemented a daemon with SIGWINCH-based TUI restoration. This balances correctness (TUI redraws itself) with implementation complexity.
+
+**Update (v1.1):** We discovered that keeping xterm instances mounted (Option A) eliminates the reattach timing issues that caused white screen flashes during workspace/tab switches. When terminal persistence is enabled, we now render all tabs and toggle visibility instead of unmounting. The SIGWINCH restoration logic remains as a fallback for app restart recovery when a fresh xterm instance must reattach to an existing PTY session.
+
+---
+
+## Future Improvements
+
+These are documented for future work. They are not blocking for the current implementation.
+
+### 1. Buffer PTY Output for Hidden Terminals
+
+Currently, hidden terminals continue processing PTY output through xterm.js. For users with many terminals producing continuous output, this wastes CPU cycles.
+
+**Proposed solution:**
+- When a terminal becomes hidden, pause writes to xterm
+- Buffer PTY events in memory (or discard if not in alt-screen mode)
+- On show, flush buffered events to xterm
+
+### 2. LRU Terminal Hibernation
+
+For users with many workspaces (10+), keeping all terminals alive may use excessive memory.
+
+**Proposed solution:**
+- Track terminal last-active timestamps
+- When memory pressure is detected, hibernate oldest inactive terminals
+- Hibernation = dispose xterm instance, keep PTY alive in daemon
+- On reactivation, create new xterm and run normal restore flow
+
+### 3. Reduce Scrollback for Hidden Terminals
+
+Each terminal's scrollback buffer can be large (default 10,000 lines).
+
+**Proposed solution:**
+- Reduce `scrollback` option for inactive terminals
+- Restore full scrollback on activation (daemon has full history)
+
+### 4. Memory Usage Metrics
+
+Add observability to understand real-world memory usage patterns:
+- Track number of terminals per user session
+- Track memory per terminal (xterm buffers + DOM)
+- Surface warnings if approaching problematic thresholds
+
+---
+
+## Reference Links
+
+- [xterm.js flow control guide](https://xtermjs.org/docs/guides/flowcontrol/) — buffering, time-sliced processing
+- [xterm.js issue #595](https://github.com/xtermjs/xterm.js/issues/595) — "Support saving and restoring of terminal state"
+- [xterm.js VT features](https://xtermjs.org/docs/api/vtfeatures/) — supported sequences
+- [xterm.js WebGL issues](https://github.com/xtermjs/xterm.js/issues/4665) — regression examples
+- [How Warp Works](https://www.warp.dev/blog/how-warp-works) — GPU-first architecture
diff --git a/apps/desktop/docs/EXTERNAL_FILES.md b/apps/desktop/docs/EXTERNAL_FILES.md
new file mode 100644
index 00000000000..9e3f5d0fca9
--- /dev/null
+++ b/apps/desktop/docs/EXTERNAL_FILES.md
@@ -0,0 +1,99 @@
+# External Files Written by Superset Desktop
+
+This document lists all files written by the Superset desktop app outside of user projects.
+Understanding these files is critical for maintaining dev/prod separation and avoiding conflicts.
+
+## Environment-Specific Directories
+
+The app uses different home directories based on environment:
+- **Development**: `~/.superset-dev/`
+- **Production**: `~/.superset/`
+
+This separation prevents dev and prod from interfering with each other.
+
+## Files in `~/.superset[-dev]/`
+
+### `bin/` - Agent Wrapper Scripts
+
+| File | Purpose |
+|------|---------|
+| `claude` | Wrapper for Claude Code CLI that injects notification hooks |
+| `codex` | Wrapper for Codex CLI that injects notification hooks |
+| `opencode` | Wrapper for OpenCode CLI that sets `OPENCODE_CONFIG_DIR` |
+
+These wrappers are added to `PATH` via shell integration, allowing them to intercept
+agent commands and inject Superset-specific configuration.
+
+### `hooks/` - Notification Hook Scripts
+
+| File | Purpose |
+|------|---------|
+| `notify.sh` | Shell script called by agents when they complete or need input |
+| `claude-settings.json` | Claude Code settings file with hook configuration |
+| `opencode/plugin/superset-notify.js` | OpenCode plugin for lifecycle events |
+
+### `zsh/` and `bash/` - Shell Integration
+
+| File | Purpose |
+|------|---------|
+| `init.zsh` | Zsh initialization script (sources .zshrc, sets up PATH) |
+| `init.bash` | Bash initialization script (sources .bashrc, sets up PATH) |
+
+## Global Files (AVOID ADDING NEW ONES)
+
+**DO NOT write to global locations** like `~/.config/`, `~/Library/`, etc.
+These cause dev/prod conflicts when both environments are running.
+
+### Known Issues with Global Files
+
+Previously, the OpenCode plugin was written to `~/.config/opencode/plugin/superset-notify.js`.
+This caused severe issues:
+1. Dev would overwrite prod's plugin with incompatible protocol
+2. Prod terminals would send events that dev's server couldn't handle
+3. Users received spam notifications for every agent message
+
+**Solution**: The global plugin is no longer written. On startup, any stale global plugin
+with our marker is deleted to prevent conflicts from older versions.
+
+## Shell RC File Modifications
+
+The app modifies shell RC files to add the Superset bin directory to PATH:
+
+| Shell | RC File | Modification |
+|-------|---------|--------------|
+| Zsh | `~/.zshrc` | Prepends `~/.superset[-dev]/bin` to PATH |
+| Bash | `~/.bashrc` | Prepends `~/.superset[-dev]/bin` to PATH |
+
+## Terminal Environment Variables
+
+Each terminal session receives these environment variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `SUPERSET_PANE_ID` | Unique identifier for the terminal pane |
+| `SUPERSET_TAB_ID` | Identifier for the containing tab |
+| `SUPERSET_WORKSPACE_ID` | Identifier for the workspace |
+| `SUPERSET_WORKSPACE_NAME` | Human-readable workspace name |
+| `SUPERSET_WORKSPACE_PATH` | Filesystem path to the workspace |
+| `SUPERSET_ROOT_PATH` | Root path of the project |
+| `SUPERSET_PORT` | Port for the notification server |
+| `SUPERSET_ENV` | Environment (`development` or `production`) |
+| `SUPERSET_HOOK_VERSION` | Hook protocol version for compatibility |
+
+## Adding New External Files
+
+Before adding new files outside of `~/.superset[-dev]/`:
+
+1. **Consider if it's necessary** - Can you use the environment-specific directory instead?
+2. **Check for conflicts** - Will dev and prod overwrite each other?
+3. **Update this document** - Add the file to the appropriate section
+4. **Add cleanup logic** - If migrating from global to local, clean up the old location
+
+## Debugging Cross-Environment Issues
+
+If you suspect dev/prod cross-talk:
+
+1. Check logs for "Environment mismatch" warnings
+2. Verify `SUPERSET_ENV` and `SUPERSET_PORT` are set correctly in terminal
+3. Delete stale global files: `rm -rf ~/.config/opencode/plugin/superset-notify.js`
+4. Restart both dev and prod apps to regenerate hooks
diff --git a/apps/desktop/docs/TERMINAL_HOST_RUNBOOK.md b/apps/desktop/docs/TERMINAL_HOST_RUNBOOK.md
new file mode 100644
index 00000000000..e4bd90796d0
--- /dev/null
+++ b/apps/desktop/docs/TERMINAL_HOST_RUNBOOK.md
@@ -0,0 +1,138 @@
+# Terminal Host Daemon — Operations Runbook
+
+Quick reference for debugging and testing the terminal persistence daemon.
+
+---
+
+## File Locations
+
+| Environment | Directory | Socket | PID | Logs |
+|-------------|-----------|--------|-----|------|
+| **Development** | `~/.superset-dev/` | `terminal-host.sock` | `terminal-host.pid` | `daemon.log` |
+| **Production** | `~/.superset/` | `terminal-host.sock` | `terminal-host.pid` | None by default |
+
+---
+
+## Common Commands
+
+```bash
+# === STATUS ===
+# Check if daemon is running
+cat ~/.superset-dev/terminal-host.pid && ps -p $(cat ~/.superset-dev/terminal-host.pid)
+
+# View daemon logs (dev only)
+cat ~/.superset-dev/daemon.log
+tail -f ~/.superset-dev/daemon.log  # Live follow
+
+# === RESTART DAEMON ===
+# Kill daemon (required to pick up code changes)
+kill -9 $(cat ~/.superset-dev/terminal-host.pid)
+# Daemon auto-restarts when app connects
+
+# === FIND ORPHANS ===
+# Dev orphan subprocesses
+ps aux | grep "pty-subprocess.*persistent-terminals" | grep -v grep
+
+# Production orphan subprocesses  
+ps aux | grep "Superset.app.*pty-subprocess" | grep -v grep
+
+# All terminal-related processes
+ps aux | grep -E "terminal-host|pty-subprocess" | grep -v grep
+
+# === CLEANUP ORPHANS ===
+# Kill all dev subprocesses
+pkill -9 -f "persistent-terminals.*pty-subprocess"
+
+# Kill all production subprocesses (careful!)
+pkill -9 -f "Superset.app.*pty-subprocess"
+```
+
+---
+
+## Testing Kill Flow
+
+1. **Kill existing daemon** (picks up code changes):
+   ```bash
+   kill -9 $(cat ~/.superset-dev/terminal-host.pid)
+   ```
+
+2. **Clear logs** (optional):
+   ```bash
+   > ~/.superset-dev/daemon.log
+   ```
+
+3. **Start dev server**, create workspace with terminals
+
+4. **Delete the workspace**
+
+5. **Check results**:
+   ```bash
+   # View kill flow in logs
+   cat ~/.superset-dev/daemon.log | grep -E "handleKill|onExit|EXIT frame|Force disposing"
+   
+   # Verify no orphans
+   ps aux | grep "pty-subprocess.*persistent-terminals" | grep -v grep
+   ```
+
+### Expected Log Flow (Success)
+```
+handleKill: calling pty.kill(SIGTERM)
+handleKill: escalating to SIGKILL        # After 2s if needed
+onExit fired: exitCode=0, signal=9
+onExit: EXIT frame sent
+Received EXIT frame
+Subprocess exited with code 0
+```
+
+### Failure Indicators
+- `Force disposing stuck session after 5000ms` — onExit never fired, fallback kicked in
+- Orphan `pty-subprocess` processes after workspace delete
+
+---
+
+## Architecture
+
+```
+App (Renderer)
+    ↓ tRPC
+Electron Main
+    ↓ Unix Socket
+terminal-host daemon          ← ~/.superset[-dev]/
+    ↓ stdin/stdout IPC
+pty-subprocess (per session)  ← Owns the PTY
+    ↓
+shell (zsh/bash)
+```
+
+**Key insight**: Daemon persists across app restarts. Code changes require daemon restart.
+
+---
+
+## Known Issues
+
+### node-pty `onExit` doesn't fire after `pty.kill(SIGTERM)`
+
+**Symptom**: Subprocess stays alive, session stuck until 5s timeout.
+
+**Solution** (implemented): Escalation watchdog in `handleKill()`:
+- 0s: Send SIGTERM
+- +2s: Escalate to SIGKILL if still alive
+- +3s: Force exit if onExit still hasn't fired
+
+**Files**: `src/main/terminal-host/pty-subprocess.ts`
+
+---
+
+## Adding Diagnostic Logging
+
+Daemon logs go to `~/.superset-dev/daemon.log`. To add logging:
+
+```typescript
+// In pty-subprocess.ts (subprocess stderr → daemon.log)
+console.error(`[pty-subprocess] your message`);
+
+// In session.ts or terminal-host.ts (daemon stdout → daemon.log)  
+console.log(`[Session ${id}] your message`);
+```
+
+Remember: **Kill daemon after code changes** to pick up new logging.
diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts
index 2ce99bdabed..62a3727c2b2 100644
--- a/apps/desktop/electron.vite.config.ts
+++ b/apps/desktop/electron.vite.config.ts
@@ -98,12 +98,18 @@ export default defineConfig({
 			"process.env.NEXT_PUBLIC_POSTHOG_HOST": JSON.stringify(
 				process.env.NEXT_PUBLIC_POSTHOG_HOST,
 			),
+			// Terminal daemon mode - for terminal session persistence
+			"process.env.SUPERSET_TERMINAL_DAEMON": JSON.stringify(
+				process.env.SUPERSET_TERMINAL_DAEMON || "",
+			),
 		},
 
 		build: {
 			rollupOptions: {
 				input: {
 					index: resolve("src/main/index.ts"),
+					"terminal-host": resolve("src/main/terminal-host/index.ts"),
+					"pty-subprocess": resolve("src/main/terminal-host/pty-subprocess.ts"),
 				},
 				output: {
 					dir: resolve(devPath, "main"),
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 978a383ab50..8975c374a69 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -64,6 +64,7 @@
 		"@xterm/addon-unicode11": "^0.8.0",
 		"@xterm/addon-web-links": "^0.11.0",
 		"@xterm/addon-webgl": "^0.18.0",
+		"@xterm/headless": "^5.5.0",
 		"@xterm/xterm": "^5.5.0",
 		"better-sqlite3": "12.5.0",
 		"bindings": "^1.5.0",
diff --git a/apps/desktop/src/lib/trpc/routers/notifications.ts b/apps/desktop/src/lib/trpc/routers/notifications.ts
index eb539b8122a..f90d264b6f6 100644
--- a/apps/desktop/src/lib/trpc/routers/notifications.ts
+++ b/apps/desktop/src/lib/trpc/routers/notifications.ts
@@ -1,6 +1,6 @@
 import { observable } from "@trpc/server/observable";
 import {
-	type AgentCompleteEvent,
+	type AgentLifecycleEvent,
 	type NotificationIds,
 	notificationsEmitter,
 } from "main/lib/notifications/server";
@@ -9,8 +9,8 @@ import { publicProcedure, router } from "..";
 
 type NotificationEvent =
 	| {
-			type: typeof NOTIFICATION_EVENTS.AGENT_COMPLETE;
-			data?: AgentCompleteEvent;
+			type: typeof NOTIFICATION_EVENTS.AGENT_LIFECYCLE;
+			data?: AgentLifecycleEvent;
 	  }
 	| { type: typeof NOTIFICATION_EVENTS.FOCUS_TAB; data?: NotificationIds };
 
@@ -18,21 +18,24 @@ export const createNotificationsRouter = () => {
 	return router({
 		subscribe: publicProcedure.subscription(() => {
 			return observable<NotificationEvent>((emit) => {
-				const onComplete = (data: AgentCompleteEvent) => {
-					emit.next({ type: NOTIFICATION_EVENTS.AGENT_COMPLETE, data });
+				const onLifecycle = (data: AgentLifecycleEvent) => {
+					emit.next({ type: NOTIFICATION_EVENTS.AGENT_LIFECYCLE, data });
 				};
 
 				const onFocusTab = (data: NotificationIds) => {
 					emit.next({ type: NOTIFICATION_EVENTS.FOCUS_TAB, data });
 				};
 
-				notificationsEmitter.on(NOTIFICATION_EVENTS.AGENT_COMPLETE, onComplete);
+				notificationsEmitter.on(
+					NOTIFICATION_EVENTS.AGENT_LIFECYCLE,
+					onLifecycle,
+				);
 				notificationsEmitter.on(NOTIFICATION_EVENTS.FOCUS_TAB, onFocusTab);
 
 				return () => {
 					notificationsEmitter.off(
-						NOTIFICATION_EVENTS.AGENT_COMPLETE,
-						onComplete,
+						NOTIFICATION_EVENTS.AGENT_LIFECYCLE,
+						onLifecycle,
 					);
 					notificationsEmitter.off(NOTIFICATION_EVENTS.FOCUS_TAB, onFocusTab);
 				};
diff --git a/apps/desktop/src/lib/trpc/routers/projects/projects.ts b/apps/desktop/src/lib/trpc/routers/projects/projects.ts
index e6381a711d7..fe4148ca722 100644
--- a/apps/desktop/src/lib/trpc/routers/projects/projects.ts
+++ b/apps/desktop/src/lib/trpc/routers/projects/projects.ts
@@ -12,7 +12,7 @@ import type { BrowserWindow } from "electron";
 import { dialog } from "electron";
 import { track } from "main/lib/analytics";
 import { localDb } from "main/lib/local-db";
-import { terminalManager } from "main/lib/terminal";
+import { getActiveTerminalManager } from "main/lib/terminal";
 import { PROJECT_COLOR_VALUES } from "shared/constants/project-colors";
 import simpleGit from "simple-git";
 import { z } from "zod";
@@ -658,9 +658,8 @@ export const createProjectsRouter = (getWindow: () => BrowserWindow | null) => {
 
 				let totalFailed = 0;
 				for (const workspace of projectWorkspaces) {
-					const terminalResult = await terminalManager.killByWorkspaceId(
-						workspace.id,
-					);
+					const terminalResult =
+						await getActiveTerminalManager().killByWorkspaceId(workspace.id);
 					totalFailed += terminalResult.failed;
 				}
 
diff --git a/apps/desktop/src/lib/trpc/routers/settings/index.ts b/apps/desktop/src/lib/trpc/routers/settings/index.ts
index abc5cd8f903..c75eab773cd 100644
--- a/apps/desktop/src/lib/trpc/routers/settings/index.ts
+++ b/apps/desktop/src/lib/trpc/routers/settings/index.ts
@@ -228,5 +228,26 @@ export const createSettingsRouter = () => {
 
 				return { success: true };
 			}),
+
+		getTerminalPersistence: publicProcedure.query(() => {
+			const row = getSettings();
+			// Default to false (terminal persistence disabled by default)
+			return row.terminalPersistence ?? false;
+		}),
+
+		setTerminalPersistence: publicProcedure
+			.input(z.object({ enabled: z.boolean() }))
+			.mutation(({ input }) => {
+				localDb
+					.insert(settings)
+					.values({ id: 1, terminalPersistence: input.enabled })
+					.onConflictDoUpdate({
+						target: settings.id,
+						set: { terminalPersistence: input.enabled },
+					})
+					.run();
+
+				return { success: true };
+			}),
 	});
 };
diff --git a/apps/desktop/src/lib/trpc/routers/terminal/terminal.ts b/apps/desktop/src/lib/trpc/routers/terminal/terminal.ts
index 725c4592d80..ab2f441fcd7 100644
--- a/apps/desktop/src/lib/trpc/routers/terminal/terminal.ts
+++ b/apps/desktop/src/lib/trpc/routers/terminal/terminal.ts
@@ -4,7 +4,7 @@ import { projects, workspaces, worktrees } from "@superset/local-db";
 import { observable } from "@trpc/server/observable";
 import { eq } from "drizzle-orm";
 import { localDb } from "main/lib/local-db";
-import { terminalManager } from "main/lib/terminal";
+import { getActiveTerminalManager } from "main/lib/terminal";
 import { z } from "zod";
 import { publicProcedure, router } from "../..";
 import { getWorkspacePath } from "../workspaces/utils/worktree";
@@ -25,6 +25,9 @@ import { resolveCwd } from "./utils";
  * - SUPERSET_PORT: The hooks server port for agent completion notifications
  */
 export const createTerminalRouter = () => {
+	// Get the active terminal manager (in-process or daemon-based)
+	const terminalManager = getActiveTerminalManager();
+
 	return router({
 		createOrAttach: publicProcedure
 			.input(
@@ -87,6 +90,8 @@ export const createTerminalRouter = () => {
 					isNew: result.isNew,
 					scrollback: result.scrollback,
 					wasRecovered: result.wasRecovered,
+					// Include snapshot for daemon mode (renderer can use for rehydration)
+					snapshot: result.snapshot,
 				};
 			}),
 
@@ -98,7 +103,25 @@ export const createTerminalRouter = () => {
 				}),
 			)
 			.mutation(async ({ input }) => {
-				terminalManager.write(input);
+				try {
+					terminalManager.write(input);
+				} catch (error) {
+					const message =
+						error instanceof Error ? error.message : "Write failed";
+
+					// If session is gone, emit exit instead of error.
+					// This completes the subscription cleanly and prevents error toast floods
+					// when workspaces with terminals are deleted.
+					if (message.includes("not found or not alive")) {
+						terminalManager.emit(`exit:${input.paneId}`, 0, "SIGTERM");
+						return;
+					}
+
+					terminalManager.emit(`error:${input.paneId}`, {
+						error: message,
+						code: "WRITE_FAILED",
+					});
+				}
 			}),
 
 		resize: publicProcedure
@@ -252,6 +275,8 @@ export const createTerminalRouter = () => {
 				return observable<
 					| { type: "data"; data: string }
 					| { type: "exit"; exitCode: number; signal?: number }
+					| { type: "disconnect"; reason: string }
+					| { type: "error"; error: string; code?: string }
 				>((emit) => {
 					const onData = (data: string) => {
 						emit.next({ type: "data", data });
@@ -262,13 +287,29 @@ export const createTerminalRouter = () => {
 						emit.complete();
 					};
 
+					const onDisconnect = (reason: string) => {
+						emit.next({ type: "disconnect", reason });
+					};
+
+					const onError = (payload: { error: string; code?: string }) => {
+						emit.next({
+							type: "error",
+							error: payload.error,
+							code: payload.code,
+						});
+					};
+
 					terminalManager.on(`data:${paneId}`, onData);
 					terminalManager.on(`exit:${paneId}`, onExit);
+					terminalManager.on(`disconnect:${paneId}`, onDisconnect);
+					terminalManager.on(`error:${paneId}`, onError);
 
 					// Cleanup on unsubscribe
 					return () => {
 						terminalManager.off(`data:${paneId}`, onData);
 						terminalManager.off(`exit:${paneId}`, onExit);
+						terminalManager.off(`disconnect:${paneId}`, onDisconnect);
+						terminalManager.off(`error:${paneId}`, onError);
 					};
 				});
 			}),
diff --git a/apps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts b/apps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts
index 4a57d0a0c8c..340ce1f3abe 100644
--- a/apps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts
+++ b/apps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts
@@ -10,7 +10,7 @@ import {
 import { and, desc, eq, isNotNull, not } from "drizzle-orm";
 import { track } from "main/lib/analytics";
 import { localDb } from "main/lib/local-db";
-import { terminalManager } from "main/lib/terminal";
+import { getActiveTerminalManager } from "main/lib/terminal";
 import { SUPERSET_DIR_NAME, WORKTREES_DIR_NAME } from "shared/constants";
 import { z } from "zod";
 import { publicProcedure, router } from "../..";
@@ -494,7 +494,7 @@ export const createWorkspacesRouter = () => {
 				await safeCheckoutBranch(project.mainRepoPath, input.branch);
 
 				// Send newline to terminals so their prompts refresh with new branch
-				terminalManager.refreshPromptsForWorkspace(workspace.id);
+				getActiveTerminalManager().refreshPromptsForWorkspace(workspace.id);
 
 				// Update the workspace - name is always the branch for branch workspaces
 				const now = Date.now();
@@ -777,7 +777,9 @@ export const createWorkspacesRouter = () => {
 				}
 
 				const activeTerminalCount =
-					terminalManager.getSessionCountByWorkspaceId(input.id);
+					await getActiveTerminalManager().getSessionCountByWorkspaceId(
+						input.id,
+					);
 
 				// Branch workspaces are non-destructive to close - no git checks needed
 				if (workspace.type === "branch") {
@@ -891,9 +893,8 @@ export const createWorkspacesRouter = () => {
 				}
 
 				// Kill all terminal processes in this workspace first
-				const terminalResult = await terminalManager.killByWorkspaceId(
-					input.id,
-				);
+				const terminalResult =
+					await getActiveTerminalManager().killByWorkspaceId(input.id);
 
 				const project = localDb
 					.select()
@@ -1412,9 +1413,8 @@ export const createWorkspacesRouter = () => {
 					throw new Error("Workspace not found");
 				}
 
-				const terminalResult = await terminalManager.killByWorkspaceId(
-					input.id,
-				);
+				const terminalResult =
+					await getActiveTerminalManager().killByWorkspaceId(input.id);
 
 				// Delete workspace record ONLY, keep worktree
 				localDb.delete(workspaces).where(eq(workspaces.id, input.id)).run();
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 6afdda3832b..b485b5af0f2 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -13,7 +13,7 @@ import { initAppState } from "./lib/app-state";
 import { authService, handleAuthDeepLink, isAuthDeepLink } from "./lib/auth";
 import { setupAutoUpdater } from "./lib/auto-updater";
 import { localDb } from "./lib/local-db";
-import { terminalManager } from "./lib/terminal";
+import { shutdownOrphanedDaemon, terminalManager } from "./lib/terminal";
 import { MainWindow } from "./windows/main";
 
 // Initialize local SQLite database (runs migrations + legacy data migration on import)
@@ -221,6 +221,10 @@ if (!gotTheLock) {
 		await app.whenReady();
 
 		await initAppState();
+
+		// Cleanup any orphaned daemon if persistence is now disabled
+		await shutdownOrphanedDaemon();
+
 		await authService.initialize();
 
 		try {
diff --git a/apps/desktop/src/main/lib/agent-setup/agent-wrappers.ts b/apps/desktop/src/main/lib/agent-setup/agent-wrappers.ts
index 0ced8cdacb6..349cdf2895c 100644
--- a/apps/desktop/src/main/lib/agent-setup/agent-wrappers.ts
+++ b/apps/desktop/src/main/lib/agent-setup/agent-wrappers.ts
@@ -12,7 +12,7 @@ import {
 export const WRAPPER_MARKER = "# Superset agent-wrapper v1";
 export const CLAUDE_SETTINGS_FILE = "claude-settings.json";
 export const OPENCODE_PLUGIN_FILE = "superset-notify.js";
-export const OPENCODE_PLUGIN_MARKER = "// Superset opencode plugin v3";
+export const OPENCODE_PLUGIN_MARKER = "// Superset opencode plugin v4";
 
 const REAL_BINARY_RESOLVER = `find_real_binary() {
   local name="$1"
@@ -72,6 +72,7 @@ export function getOpenCodeGlobalPluginPath(): string {
 export function getClaudeSettingsContent(notifyPath: string): string {
 	const settings = {
 		hooks: {
+			UserPromptSubmit: [{ hooks: [{ type: "command", command: notifyPath }] }],
 			Stop: [{ hooks: [{ type: "command", command: notifyPath }] }],
 			PermissionRequest: [
 				{ matcher: "*", hooks: [{ type: "command", command: notifyPath }] },
@@ -144,7 +145,7 @@ export function getOpenCodePluginContent(notifyPath: string): string {
 		" * Superset Notification Plugin for OpenCode",
 		" *",
 		" * This plugin sends desktop notifications when OpenCode sessions need attention.",
-		" * It hooks into session.idle, session.error, and permission.ask events.",
+		" * It hooks into session.status (busy/idle), session.error, and permission.ask events.",
 		" *",
 		" * IMPORTANT: Subagent/Background Task Filtering",
 		" * --------------------------------------------",
@@ -164,8 +165,8 @@ export function getOpenCodePluginContent(notifyPath: string): string {
 		" * @see https://github.com/sst/opencode/blob/dev/packages/app/src/context/notification.tsx",
 		" */",
 		"export const SupersetNotifyPlugin = async ({ $, client }) => {",
-		"  if (globalThis.__supersetOpencodeNotifyPluginV3) return {};",
-		"  globalThis.__supersetOpencodeNotifyPluginV3 = true;",
+		"  if (globalThis.__supersetOpencodeNotifyPluginV4) return {};",
+		"  globalThis.__supersetOpencodeNotifyPluginV4 = true;",
 		"",
 		"  // Only run inside a Superset terminal session",
 		"  if (!process?.env?.SUPERSET_TAB_ID) return {};",
@@ -216,16 +217,29 @@ export function getOpenCodePluginContent(notifyPath: string): string {
 		"",
 		"  return {",
 		"    event: async ({ event }) => {",
-		"      // Handle session completion events",
-		'      if (event.type === "session.idle" || event.type === "session.error") {',
+		"      // Handle session status changes (busy = working, idle = done)",
+		'      if (event.type === "session.status") {',
 		"        const sessionID = event.properties?.sessionID;",
+		"        const status = event.properties?.status;",
 		"",
 		"        // Skip notifications for child/subagent sessions",
-		"        // This prevents notification spam when background agents complete",
 		"        if (await isChildSession(sessionID)) {",
 		"          return;",
 		"        }",
 		"",
+		'        if (status?.type === "busy") {',
+		'          await notify("Start");',
+		'        } else if (status?.type === "idle") {',
+		'          await notify("Stop");',
+		"        }",
+		"      }",
+		"",
+		"      // Handle session errors (also means session stopped)",
+		'      if (event.type === "session.error") {',
+		"        const sessionID = event.properties?.sessionID;",
+		"        if (await isChildSession(sessionID)) {",
+		"          return;",
+		"        }",
 		'        await notify("Stop");',
 		"      }",
 		"    },",
@@ -275,24 +289,43 @@ export function createCodexWrapper(): void {
 }
 
 /**
- * Creates OpenCode plugin file with notification hooks
+ * Creates OpenCode plugin file with notification hooks.
+ * Only writes to environment-specific path - NOT the global path.
+ * Global path causes dev/prod conflicts when both are running.
  */
 export function createOpenCodePlugin(): void {
 	const pluginPath = getOpenCodePluginPath();
 	const notifyPath = getNotifyScriptPath();
 	const content = getOpenCodePluginContent(notifyPath);
 	fs.writeFileSync(pluginPath, content, { mode: 0o644 });
+	console.log("[agent-setup] Created OpenCode plugin");
+}
+
+/**
+ * Cleans up stale global OpenCode plugin that may have been written by older versions.
+ * Only removes if the file contains our marker to avoid deleting user-installed plugins.
+ * This prevents dev/prod cross-talk when both environments are running.
+ */
+export function cleanupGlobalOpenCodePlugin(): void {
 	try {
 		const globalPluginPath = getOpenCodeGlobalPluginPath();
-		fs.mkdirSync(path.dirname(globalPluginPath), { recursive: true });
-		fs.writeFileSync(globalPluginPath, content, { mode: 0o644 });
+		if (!fs.existsSync(globalPluginPath)) return;
+
+		const content = fs.readFileSync(globalPluginPath, "utf-8");
+		// Check for any version of our marker (v1, v2, v3, v4, etc.)
+		if (content.includes("// Superset opencode plugin")) {
+			fs.unlinkSync(globalPluginPath);
+			console.log(
+				"[agent-setup] Removed stale global OpenCode plugin to prevent dev/prod conflicts",
+			);
+		}
 	} catch (error) {
+		// Ignore errors - this is best-effort cleanup
 		console.warn(
-			"[agent-setup] Failed to write global OpenCode plugin:",
+			"[agent-setup] Failed to cleanup global OpenCode plugin:",
 			error,
 		);
 	}
-	console.log("[agent-setup] Created OpenCode plugin");
 }
 
 /**
diff --git a/apps/desktop/src/main/lib/agent-setup/index.ts b/apps/desktop/src/main/lib/agent-setup/index.ts
index d0ac5cb3ea4..e2ca3b6c82a 100644
--- a/apps/desktop/src/main/lib/agent-setup/index.ts
+++ b/apps/desktop/src/main/lib/agent-setup/index.ts
@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import {
+	cleanupGlobalOpenCodePlugin,
 	createClaudeWrapper,
 	createCodexWrapper,
 	createOpenCodePlugin,
@@ -34,6 +35,9 @@ export function setupAgentHooks(): void {
 	fs.mkdirSync(BASH_DIR, { recursive: true });
 	fs.mkdirSync(OPENCODE_PLUGIN_DIR, { recursive: true });
 
+	// Clean up stale global plugins that may cause dev/prod conflicts
+	cleanupGlobalOpenCodePlugin();
+
 	// Create scripts
 	createNotifyScript();
 	createClaudeWrapper();
diff --git a/apps/desktop/src/main/lib/agent-setup/notify-hook.ts b/apps/desktop/src/main/lib/agent-setup/notify-hook.ts
index c583486a9a5..6940eca38f4 100644
--- a/apps/desktop/src/main/lib/agent-setup/notify-hook.ts
+++ b/apps/desktop/src/main/lib/agent-setup/notify-hook.ts
@@ -26,17 +26,26 @@ else
 fi
 
 # Extract event type - Claude uses "hook_event_name", Codex uses "type"
-EVENT_TYPE=$(echo "$INPUT" | grep -o '"hook_event_name":"[^"]*"' | cut -d'"' -f4)
+# Use flexible pattern to handle optional whitespace: "key": "value" or "key":"value"
+EVENT_TYPE=$(echo "$INPUT" | grep -oE '"hook_event_name"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -oE '"[^"]*"$' | tr -d '"')
 if [ -z "$EVENT_TYPE" ]; then
   # Check for Codex "type" field (e.g., "agent-turn-complete")
-  CODEX_TYPE=$(echo "$INPUT" | grep -o '"type":"[^"]*"' | cut -d'"' -f4)
+  CODEX_TYPE=$(echo "$INPUT" | grep -oE '"type"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -oE '"[^"]*"$' | tr -d '"')
   if [ "$CODEX_TYPE" = "agent-turn-complete" ]; then
     EVENT_TYPE="Stop"
   fi
 fi
 
-# Default to "Stop" if not found
-[ -z "$EVENT_TYPE" ] && EVENT_TYPE="Stop"
+# NOTE: We intentionally do NOT default to "Stop" if EVENT_TYPE is empty.
+# Parse failures should not trigger completion notifications.
+# The server will ignore requests with missing eventType (forward compatibility).
+
+# Map UserPromptSubmit to Start for simpler handling
+[ "$EVENT_TYPE" = "UserPromptSubmit" ] && EVENT_TYPE="Start"
+
+# If no event type was found, skip the notification
+# This prevents parse failures from causing false completion notifications
+[ -z "$EVENT_TYPE" ] && exit 0
 
 # Timeouts prevent blocking agent completion if notification server is unresponsive
 curl -sG "http://127.0.0.1:\${SUPERSET_PORT:-${PORTS.NOTIFICATIONS}}/hook/complete" \\
@@ -45,6 +54,8 @@ curl -sG "http://127.0.0.1:\${SUPERSET_PORT:-${PORTS.NOTIFICATIONS}}/hook/comple
   --data-urlencode "tabId=$SUPERSET_TAB_ID" \\
   --data-urlencode "workspaceId=$SUPERSET_WORKSPACE_ID" \\
   --data-urlencode "eventType=$EVENT_TYPE" \\
+  --data-urlencode "env=$SUPERSET_ENV" \\
+  --data-urlencode "version=$SUPERSET_HOOK_VERSION" \\
   > /dev/null 2>&1
 `;
 }
diff --git a/apps/desktop/src/main/lib/notifications/server.test.ts b/apps/desktop/src/main/lib/notifications/server.test.ts
new file mode 100644
index 00000000000..94e095508e9
--- /dev/null
+++ b/apps/desktop/src/main/lib/notifications/server.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "bun:test";
+import { mapEventType } from "./server";
+
+describe("notifications/server", () => {
+	describe("mapEventType", () => {
+		it("should map 'Start' to 'Start'", () => {
+			expect(mapEventType("Start")).toBe("Start");
+		});
+
+		it("should map 'UserPromptSubmit' to 'Start'", () => {
+			expect(mapEventType("UserPromptSubmit")).toBe("Start");
+		});
+
+		it("should map 'Stop' to 'Stop'", () => {
+			expect(mapEventType("Stop")).toBe("Stop");
+		});
+
+		it("should map 'agent-turn-complete' to 'Stop'", () => {
+			expect(mapEventType("agent-turn-complete")).toBe("Stop");
+		});
+
+		it("should map 'PermissionRequest' to 'PermissionRequest'", () => {
+			expect(mapEventType("PermissionRequest")).toBe("PermissionRequest");
+		});
+
+		it("should return null for unknown event types (forward compatibility)", () => {
+			expect(mapEventType("UnknownEvent")).toBeNull();
+			expect(mapEventType("FutureEvent")).toBeNull();
+			expect(mapEventType("SomeNewHook")).toBeNull();
+		});
+
+		it("should return null for undefined eventType (not default to Stop)", () => {
+			// This is critical: missing eventType should NOT trigger a completion notification
+			expect(mapEventType(undefined)).toBeNull();
+		});
+
+		it("should return null for empty string eventType", () => {
+			expect(mapEventType("")).toBeNull();
+		});
+	});
+});
diff --git a/apps/desktop/src/main/lib/notifications/server.ts b/apps/desktop/src/main/lib/notifications/server.ts
index a27398d46f0..3c72e753a1f 100644
--- a/apps/desktop/src/main/lib/notifications/server.ts
+++ b/apps/desktop/src/main/lib/notifications/server.ts
@@ -1,6 +1,15 @@
 import { EventEmitter } from "node:events";
 import express from "express";
 import { NOTIFICATION_EVENTS } from "shared/constants";
+import { env } from "shared/env.shared";
+import { appState } from "../app-state";
+
+/**
+ * The environment this server is running in.
+ * Used to validate incoming hook requests and detect cross-environment issues.
+ */
+const SERVER_ENV =
+	env.NODE_ENV === "development" ? "development" : "production";
 
 export interface NotificationIds {
 	paneId?: string;
@@ -8,8 +17,8 @@ export interface NotificationIds {
 	workspaceId?: string;
 }
 
-export interface AgentCompleteEvent extends NotificationIds {
-	eventType: "Stop" | "PermissionRequest";
+export interface AgentLifecycleEvent extends NotificationIds {
+	eventType: "Start" | "Stop" | "PermissionRequest";
 }
 
 export const notificationsEmitter = new EventEmitter();
@@ -29,20 +38,127 @@ app.use((req, res, next) => {
 	next();
 });
 
-// Agent completion hook
+/**
+ * Maps incoming event types to canonical lifecycle events.
+ * Handles variations from different agent CLIs.
+ *
+ * Returns null for unknown events - caller should ignore these gracefully
+ * to maintain forward compatibility with newer hook versions.
+ *
+ * Note: We no longer default missing eventType to "Stop" to prevent
+ * parse failures from being treated as completions.
+ *
+ * @internal Exported for testing
+ */
+export function mapEventType(
+	eventType: string | undefined,
+): "Start" | "Stop" | "PermissionRequest" | null {
+	if (!eventType) {
+		return null; // Missing eventType should be ignored, not treated as Stop
+	}
+	if (eventType === "Start" || eventType === "UserPromptSubmit") {
+		return "Start";
+	}
+	if (eventType === "PermissionRequest") {
+		return "PermissionRequest";
+	}
+	if (eventType === "Stop" || eventType === "agent-turn-complete") {
+		return "Stop";
+	}
+	return null; // Unknown events are ignored for forward compatibility
+}
+
+/**
+ * Resolves paneId from tabId or workspaceId using synced tabs state.
+ * Falls back to focused pane in active tab.
+ */
+function resolvePaneId(
+	paneId: string | undefined,
+	tabId: string | undefined,
+	workspaceId: string | undefined,
+): string | undefined {
+	if (paneId) return paneId;
+
+	try {
+		const tabsState = appState.data.tabsState;
+		if (!tabsState) return undefined;
+
+		// Try to resolve from tabId
+		if (tabId) {
+			const focusedPaneId = tabsState.focusedPaneIds?.[tabId];
+			if (focusedPaneId) return focusedPaneId;
+		}
+
+		// Try to resolve from workspaceId
+		if (workspaceId) {
+			const activeTabId = tabsState.activeTabIds?.[workspaceId];
+			if (activeTabId) {
+				const focusedPaneId = tabsState.focusedPaneIds?.[activeTabId];
+				if (focusedPaneId) return focusedPaneId;
+			}
+		}
+	} catch {
+		// App state not initialized yet, ignore
+	}
+
+	return undefined;
+}
+
+// Agent lifecycle hook
 app.get("/hook/complete", (req, res) => {
-	const { paneId, tabId, workspaceId, eventType } = req.query;
+	const {
+		paneId,
+		tabId,
+		workspaceId,
+		eventType,
+		env: clientEnv,
+		version,
+	} = req.query;
+
+	// Environment validation: detect dev/prod cross-talk
+	// We still return success to not block the agent, but log a warning
+	if (clientEnv && clientEnv !== SERVER_ENV) {
+		console.warn(
+			`[notifications] Environment mismatch: received ${clientEnv} request on ${SERVER_ENV} server. ` +
+				`This may indicate a stale hook or misconfigured terminal. Ignoring request.`,
+		);
+		return res.json({ success: true, ignored: true, reason: "env_mismatch" });
+	}
+
+	// Log version for debugging (helpful when troubleshooting hook issues)
+	if (version && version !== "2") {
+		console.log(
+			`[notifications] Received hook v${version} request (server expects v2)`,
+		);
+	}
+
+	const mappedEventType = mapEventType(eventType as string | undefined);
+
+	// Unknown or missing eventType: return success but don't process
+	// This ensures forward compatibility and doesn't block the agent
+	if (!mappedEventType) {
+		if (eventType) {
+			console.log("[notifications] Ignoring unknown eventType:", eventType);
+		}
+		return res.json({ success: true, ignored: true });
+	}
+
+	const resolvedPaneId = resolvePaneId(
+		paneId as string | undefined,
+		tabId as string | undefined,
+		workspaceId as string | undefined,
+	);
 
-	const event: AgentCompleteEvent = {
-		paneId: paneId as string | undefined,
+	const event: AgentLifecycleEvent = {
+		paneId: resolvedPaneId,
 		tabId: tabId as string | undefined,
 		workspaceId: workspaceId as string | undefined,
-		eventType: eventType === "PermissionRequest" ? "PermissionRequest" : "Stop",
+		eventType: mappedEventType,
 	};
 
-	notificationsEmitter.emit(NOTIFICATION_EVENTS.AGENT_COMPLETE, event);
+	notificationsEmitter.emit(NOTIFICATION_EVENTS.AGENT_LIFECYCLE, event);
 
-	res.json({ success: true, paneId, tabId });
+	res.json({ success: true, paneId: resolvedPaneId, tabId });
 });
 
 // Health check
diff --git a/apps/desktop/src/main/lib/terminal-host/__tests__/headless-roundtrip.test.ts b/apps/desktop/src/main/lib/terminal-host/__tests__/headless-roundtrip.test.ts
new file mode 100644
index 00000000000..c04e6a023f1
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal-host/__tests__/headless-roundtrip.test.ts
@@ -0,0 +1,529 @@
+/**
+ * Headless Terminal Round-Trip Test
+ *
+ * This test proves that we can:
+ * 1. Feed terminal output into a headless emulator
+ * 2. Capture mode state changes (application cursor keys, bracketed paste, mouse tracking)
+ * 3. Serialize the terminal state
+ * 4. Apply that state to a fresh emulator
+ * 5. Verify the restored terminal has matching visual content and mode flags
+ *
+ * This is the foundational proof for "perfect resume" - the ability to restore
+ * terminal sessions across app restarts.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { HeadlessEmulator, modesEqual } from "../headless-emulator";
+import { DEFAULT_MODES } from "../types";
+
+// Escape sequences for testing
+const ESC = "\x1b";
+const CSI = `${ESC}[`;
+const OSC = `${ESC}]`;
+const BEL = "\x07";
+
+// Mode enable/disable sequences
+const ENABLE_APP_CURSOR = `${CSI}?1h`;
+const DISABLE_APP_CURSOR = `${CSI}?1l`;
+const ENABLE_BRACKETED_PASTE = `${CSI}?2004h`;
+const DISABLE_BRACKETED_PASTE = `${CSI}?2004l`;
+const ENABLE_MOUSE_SGR = `${CSI}?1006h`;
+const DISABLE_MOUSE_SGR = `${CSI}?1006l`;
+const ENABLE_MOUSE_NORMAL = `${CSI}?1000h`;
+const DISABLE_MOUSE_NORMAL = `${CSI}?1000l`;
+const ENABLE_FOCUS_REPORTING = `${CSI}?1004h`;
+const HIDE_CURSOR = `${CSI}?25l`;
+const SHOW_CURSOR = `${CSI}?25h`;
+const ENTER_ALT_SCREEN = `${CSI}?1049h`;
+const EXIT_ALT_SCREEN = `${CSI}?1049l`;
+
+// Cursor movement
+const MOVE_CURSOR = (row: number, col: number) => `${CSI}${row};${col}H`;
+const CLEAR_SCREEN = `${CSI}2J`;
+
+// OSC-7 CWD reporting - format is file://hostname/path (path is NOT URL-encoded)
+const OSC7_CWD = (path: string) => `${OSC}7;file://localhost${path}${BEL}`;
+
+describe("HeadlessEmulator", () => {
+	let emulator: HeadlessEmulator;
+
+	beforeEach(() => {
+		emulator = new HeadlessEmulator({ cols: 80, rows: 24, scrollback: 1000 });
+	});
+
+	afterEach(() => {
+		emulator.dispose();
+	});
+
+	describe("basic functionality", () => {
+		test("should initialize with default modes", () => {
+			const modes = emulator.getModes();
+			expect(modesEqual(modes, DEFAULT_MODES)).toBe(true);
+		});
+
+		test("should write text to terminal", async () => {
+			await emulator.writeSync("Hello, World!\r\n");
+			const snapshot = emulator.getSnapshot();
+			expect(snapshot.snapshotAnsi).toContain("Hello, World!");
+		});
+
+		test("should track dimensions", () => {
+			const dims = emulator.getDimensions();
+			expect(dims.cols).toBe(80);
+			expect(dims.rows).toBe(24);
+		});
+
+		test("should resize terminal", () => {
+			emulator.resize(120, 40);
+			const dims = emulator.getDimensions();
+			expect(dims.cols).toBe(120);
+			expect(dims.rows).toBe(40);
+		});
+	});
+
+	describe("mode tracking", () => {
+		test("should track application cursor keys mode", async () => {
+			expect(emulator.getModes().applicationCursorKeys).toBe(false);
+
+			await emulator.writeSync(ENABLE_APP_CURSOR);
+			expect(emulator.getModes().applicationCursorKeys).toBe(true);
+
+			await emulator.writeSync(DISABLE_APP_CURSOR);
+			expect(emulator.getModes().applicationCursorKeys).toBe(false);
+		});
+
+		test("should track bracketed paste mode", async () => {
+			expect(emulator.getModes().bracketedPaste).toBe(false);
+
+			await emulator.writeSync(ENABLE_BRACKETED_PASTE);
+			expect(emulator.getModes().bracketedPaste).toBe(true);
+
+			await emulator.writeSync(DISABLE_BRACKETED_PASTE);
+			expect(emulator.getModes().bracketedPaste).toBe(false);
+		});
+
+		test("should track mouse SGR mode", async () => {
+			expect(emulator.getModes().mouseSgr).toBe(false);
+
+			await emulator.writeSync(ENABLE_MOUSE_SGR);
+			expect(emulator.getModes().mouseSgr).toBe(true);
+
+			await emulator.writeSync(DISABLE_MOUSE_SGR);
+			expect(emulator.getModes().mouseSgr).toBe(false);
+		});
+
+		test("should track mouse normal tracking mode", async () => {
+			expect(emulator.getModes().mouseTrackingNormal).toBe(false);
+
+			await emulator.writeSync(ENABLE_MOUSE_NORMAL);
+			expect(emulator.getModes().mouseTrackingNormal).toBe(true);
+
+			await emulator.writeSync(DISABLE_MOUSE_NORMAL);
+			expect(emulator.getModes().mouseTrackingNormal).toBe(false);
+		});
+
+		test("should track focus reporting mode", async () => {
+			expect(emulator.getModes().focusReporting).toBe(false);
+
+			await emulator.writeSync(ENABLE_FOCUS_REPORTING);
+			expect(emulator.getModes().focusReporting).toBe(true);
+		});
+
+		test("should track cursor visibility", async () => {
+			expect(emulator.getModes().cursorVisible).toBe(true); // Default is visible
+
+			await emulator.writeSync(HIDE_CURSOR);
+			expect(emulator.getModes().cursorVisible).toBe(false);
+
+			await emulator.writeSync(SHOW_CURSOR);
+			expect(emulator.getModes().cursorVisible).toBe(true);
+		});
+
+		test("should track alternate screen mode", async () => {
+			expect(emulator.getModes().alternateScreen).toBe(false);
+
+			await emulator.writeSync(ENTER_ALT_SCREEN);
+			expect(emulator.getModes().alternateScreen).toBe(true);
+
+			await emulator.writeSync(EXIT_ALT_SCREEN);
+			expect(emulator.getModes().alternateScreen).toBe(false);
+		});
+
+		test("should handle multiple modes in single sequence", async () => {
+			// Enable both app cursor and bracketed paste in one sequence
+			await emulator.writeSync(`${CSI}?1;2004h`);
+
+			const modes = emulator.getModes();
+			expect(modes.applicationCursorKeys).toBe(true);
+			expect(modes.bracketedPaste).toBe(true);
+		});
+	});
+
+	describe("CWD tracking via OSC-7", () => {
+		test("should parse OSC-7 with BEL terminator", async () => {
+			expect(emulator.getCwd()).toBeNull();
+
+			await emulator.writeSync(OSC7_CWD("/Users/test/project"));
+			expect(emulator.getCwd()).toBe("/Users/test/project");
+		});
+
+		test("should update CWD on directory change", async () => {
+			await emulator.writeSync(OSC7_CWD("/Users/test"));
+			expect(emulator.getCwd()).toBe("/Users/test");
+
+			await emulator.writeSync(OSC7_CWD("/Users/test/subdir"));
+			expect(emulator.getCwd()).toBe("/Users/test/subdir");
+		});
+
+		test("should handle paths with spaces", async () => {
+			await emulator.writeSync(OSC7_CWD("/Users/test/my project"));
+			expect(emulator.getCwd()).toBe("/Users/test/my project");
+		});
+	});
+
+	describe("snapshot generation", () => {
+		test("should generate snapshot with screen content", async () => {
+			await emulator.writeSync("Line 1\r\nLine 2\r\nLine 3\r\n");
+
+			const snapshot = emulator.getSnapshot();
+
+			expect(snapshot.snapshotAnsi).toBeDefined();
+			expect(snapshot.snapshotAnsi.length).toBeGreaterThan(0);
+			expect(snapshot.cols).toBe(80);
+			expect(snapshot.rows).toBe(24);
+		});
+
+		test("should include mode state in snapshot", async () => {
+			await emulator.writeSync(ENABLE_APP_CURSOR);
+			await emulator.writeSync(ENABLE_BRACKETED_PASTE);
+			await emulator.writeSync(ENABLE_MOUSE_SGR);
+
+			const snapshot = emulator.getSnapshot();
+
+			expect(snapshot.modes.applicationCursorKeys).toBe(true);
+			expect(snapshot.modes.bracketedPaste).toBe(true);
+			expect(snapshot.modes.mouseSgr).toBe(true);
+		});
+
+		test("should include CWD in snapshot", async () => {
+			await emulator.writeSync(OSC7_CWD("/home/user/workspace"));
+
+			const snapshot = emulator.getSnapshot();
+
+			expect(snapshot.cwd).toBe("/home/user/workspace");
+		});
+
+		test("should generate rehydrate sequences for non-default modes", async () => {
+			await emulator.writeSync(ENABLE_APP_CURSOR);
+			await emulator.writeSync(ENABLE_BRACKETED_PASTE);
+
+			const snapshot = emulator.getSnapshot();
+
+			// Rehydrate sequences should contain mode-setting escapes
+			expect(snapshot.rehydrateSequences).toContain("?1h"); // app cursor
+			expect(snapshot.rehydrateSequences).toContain("?2004h"); // bracketed paste
+		});
+
+		test("should not generate rehydrate sequences for default modes", async () => {
+			// Don't change any modes - use defaults
+			await emulator.writeSync("Some text\r\n");
+
+			const snapshot = emulator.getSnapshot();
+
+			// Should have empty or minimal rehydrate sequences
+			expect(snapshot.rehydrateSequences).toBe("");
+		});
+	});
+});
+
+describe("Snapshot Round-Trip", () => {
+	test("should restore simple text content", async () => {
+		const source = new HeadlessEmulator({ cols: 80, rows: 24 });
+		const target = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Write content to source
+			await source.writeSync("Hello, World!\r\n");
+			await source.writeSync("This is line 2\r\n");
+			await source.writeSync("And line 3\r\n");
+
+			// Get snapshot and apply to target
+			const snapshot = source.getSnapshot();
+			await target.writeSync(snapshot.rehydrateSequences);
+			await target.writeSync(snapshot.snapshotAnsi);
+
+			// Verify content matches
+			const targetSnapshot = target.getSnapshot();
+			expect(targetSnapshot.snapshotAnsi).toContain("Hello, World!");
+			expect(targetSnapshot.snapshotAnsi).toContain("This is line 2");
+			expect(targetSnapshot.snapshotAnsi).toContain("And line 3");
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+
+	test("should restore mode state", async () => {
+		const source = new HeadlessEmulator({ cols: 80, rows: 24 });
+		const target = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Set up modes in source
+			await source.writeSync(ENABLE_APP_CURSOR);
+			await source.writeSync(ENABLE_BRACKETED_PASTE);
+			await source.writeSync(ENABLE_MOUSE_NORMAL);
+			await source.writeSync(ENABLE_MOUSE_SGR);
+
+			// Get snapshot
+			const snapshot = source.getSnapshot();
+
+			// Verify source modes
+			expect(snapshot.modes.applicationCursorKeys).toBe(true);
+			expect(snapshot.modes.bracketedPaste).toBe(true);
+			expect(snapshot.modes.mouseTrackingNormal).toBe(true);
+			expect(snapshot.modes.mouseSgr).toBe(true);
+
+			// Apply snapshot to target using applySnapshot helper
+			await applySnapshotAsync(target, snapshot);
+
+			// Verify target modes match
+			const targetModes = target.getModes();
+			expect(targetModes.applicationCursorKeys).toBe(true);
+			expect(targetModes.bracketedPaste).toBe(true);
+			expect(targetModes.mouseTrackingNormal).toBe(true);
+			expect(targetModes.mouseSgr).toBe(true);
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+
+	test("should restore cursor position and screen state", async () => {
+		const source = new HeadlessEmulator({ cols: 80, rows: 24 });
+		const target = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Draw a simple screen with cursor at specific position
+			await source.writeSync(CLEAR_SCREEN);
+			await source.writeSync(MOVE_CURSOR(1, 1));
+			await source.writeSync("Top left");
+			await source.writeSync(MOVE_CURSOR(12, 40));
+			await source.writeSync("Center");
+			await source.writeSync(MOVE_CURSOR(24, 70));
+			await source.writeSync("Bottom right");
+
+			// Get snapshot and apply
+			const snapshot = source.getSnapshot();
+			await applySnapshotAsync(target, snapshot);
+
+			// Verify screen content
+			const targetSnapshot = target.getSnapshot();
+			expect(targetSnapshot.snapshotAnsi).toContain("Top left");
+			expect(targetSnapshot.snapshotAnsi).toContain("Center");
+			expect(targetSnapshot.snapshotAnsi).toContain("Bottom right");
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+
+	test("should handle TUI-like screen with modes enabled", async () => {
+		const source = new HeadlessEmulator({ cols: 80, rows: 24 });
+		const target = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Simulate a TUI application setup (like vim, htop, etc.)
+			// Enter alternate screen
+			await source.writeSync(ENTER_ALT_SCREEN);
+			// Enable application cursor keys
+			await source.writeSync(ENABLE_APP_CURSOR);
+			// Enable bracketed paste
+			await source.writeSync(ENABLE_BRACKETED_PASTE);
+			// Enable mouse tracking with SGR encoding
+			await source.writeSync(ENABLE_MOUSE_NORMAL);
+			await source.writeSync(ENABLE_MOUSE_SGR);
+			// Hide cursor
+			await source.writeSync(HIDE_CURSOR);
+			// Clear and draw
+			await source.writeSync(CLEAR_SCREEN);
+			await source.writeSync(MOVE_CURSOR(1, 1));
+			await source.writeSync("=== TUI Application ===");
+			await source.writeSync(MOVE_CURSOR(3, 1));
+			await source.writeSync("Press q to quit");
+			await source.writeSync(MOVE_CURSOR(24, 1));
+			await source.writeSync("[Status Bar]");
+
+			// Get snapshot
+			const snapshot = source.getSnapshot();
+
+			// Verify all modes are captured
+			expect(snapshot.modes.alternateScreen).toBe(true);
+			expect(snapshot.modes.applicationCursorKeys).toBe(true);
+			expect(snapshot.modes.bracketedPaste).toBe(true);
+			expect(snapshot.modes.mouseTrackingNormal).toBe(true);
+			expect(snapshot.modes.mouseSgr).toBe(true);
+			expect(snapshot.modes.cursorVisible).toBe(false);
+
+			// Apply to target
+			await applySnapshotAsync(target, snapshot);
+
+			// Verify target modes
+			const targetModes = target.getModes();
+			expect(targetModes.applicationCursorKeys).toBe(true);
+			expect(targetModes.bracketedPaste).toBe(true);
+			expect(targetModes.mouseTrackingNormal).toBe(true);
+			expect(targetModes.mouseSgr).toBe(true);
+			expect(targetModes.cursorVisible).toBe(false);
+
+			// Note: alternateScreen mode is handled by the snapshot itself,
+			// not by rehydrate sequences (since the serialized content already
+			// represents the correct screen buffer)
+
+			// Verify content
+			const targetSnapshot = target.getSnapshot();
+			expect(targetSnapshot.snapshotAnsi).toContain("TUI Application");
+			expect(targetSnapshot.snapshotAnsi).toContain("Press q to quit");
+			expect(targetSnapshot.snapshotAnsi).toContain("[Status Bar]");
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+
+	test("should preserve scrollback content", async () => {
+		const source = new HeadlessEmulator({
+			cols: 80,
+			rows: 5,
+			scrollback: 100,
+		});
+		const target = new HeadlessEmulator({
+			cols: 80,
+			rows: 5,
+			scrollback: 100,
+		});
+
+		try {
+			// Write many lines to create scrollback
+			for (let i = 1; i <= 20; i++) {
+				await source.writeSync(`Line ${i}\r\n`);
+			}
+
+			const snapshot = source.getSnapshot();
+
+			// Verify scrollback is captured
+			expect(snapshot.scrollbackLines).toBeGreaterThan(5);
+
+			// Apply to target
+			await applySnapshotAsync(target, snapshot);
+
+			// Verify scrollback content is restored
+			const targetSnapshot = target.getSnapshot();
+			expect(targetSnapshot.snapshotAnsi).toContain("Line 1");
+			expect(targetSnapshot.snapshotAnsi).toContain("Line 10");
+			expect(targetSnapshot.snapshotAnsi).toContain("Line 20");
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+});
+
+describe("Edge Cases", () => {
+	test("should handle rapid mode toggling", async () => {
+		const emulator = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Rapidly toggle modes
+			for (let i = 0; i < 10; i++) {
+				await emulator.writeSync(ENABLE_APP_CURSOR);
+				await emulator.writeSync(DISABLE_APP_CURSOR);
+				await emulator.writeSync(ENABLE_BRACKETED_PASTE);
+				await emulator.writeSync(DISABLE_BRACKETED_PASTE);
+			}
+
+			// Should end at default state
+			const modes = emulator.getModes();
+			expect(modes.applicationCursorKeys).toBe(false);
+			expect(modes.bracketedPaste).toBe(false);
+		} finally {
+			emulator.dispose();
+		}
+	});
+
+	test("should handle interleaved content and mode changes", async () => {
+		const emulator = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			await emulator.writeSync("Before modes\r\n");
+			await emulator.writeSync(ENABLE_APP_CURSOR);
+			await emulator.writeSync("After app cursor\r\n");
+			await emulator.writeSync(ENABLE_BRACKETED_PASTE);
+			await emulator.writeSync("After bracketed paste\r\n");
+			await emulator.writeSync(OSC7_CWD("/test/path"));
+			await emulator.writeSync("After CWD\r\n");
+
+			const snapshot = emulator.getSnapshot();
+
+			expect(snapshot.modes.applicationCursorKeys).toBe(true);
+			expect(snapshot.modes.bracketedPaste).toBe(true);
+			expect(snapshot.cwd).toBe("/test/path");
+			expect(snapshot.snapshotAnsi).toContain("Before modes");
+			expect(snapshot.snapshotAnsi).toContain("After CWD");
+		} finally {
+			emulator.dispose();
+		}
+	});
+
+	test("should handle empty terminal", async () => {
+		const emulator = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			// Flush to ensure terminal is ready
+			await emulator.flush();
+			const snapshot = emulator.getSnapshot();
+
+			expect(snapshot.cols).toBe(80);
+			expect(snapshot.rows).toBe(24);
+			expect(snapshot.cwd).toBeNull();
+			expect(modesEqual(snapshot.modes, DEFAULT_MODES)).toBe(true);
+		} finally {
+			emulator.dispose();
+		}
+	});
+
+	test("should handle resize during session", async () => {
+		const source = new HeadlessEmulator({ cols: 80, rows: 24 });
+		const target = new HeadlessEmulator({ cols: 80, rows: 24 });
+
+		try {
+			await source.writeSync("Initial content\r\n");
+			source.resize(120, 40);
+			await source.writeSync("After resize\r\n");
+
+			const snapshot = source.getSnapshot();
+
+			expect(snapshot.cols).toBe(120);
+			expect(snapshot.rows).toBe(40);
+
+			// Resize target to match before applying
+			target.resize(120, 40);
+			await applySnapshotAsync(target, snapshot);
+
+			const targetSnapshot = target.getSnapshot();
+			expect(targetSnapshot.snapshotAnsi).toContain("Initial content");
+			expect(targetSnapshot.snapshotAnsi).toContain("After resize");
+		} finally {
+			source.dispose();
+			target.dispose();
+		}
+	});
+});
+
+// Helper function to apply snapshot asynchronously
+async function applySnapshotAsync(
+	emulator: HeadlessEmulator,
+	snapshot: { rehydrateSequences: string; snapshotAnsi: string },
+): Promise<void> {
+	await emulator.writeSync(snapshot.rehydrateSequences);
+	await emulator.writeSync(snapshot.snapshotAnsi);
+}
diff --git a/apps/desktop/src/main/lib/terminal-host/client.ts b/apps/desktop/src/main/lib/terminal-host/client.ts
new file mode 100644
index 00000000000..5e44172f35b
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal-host/client.ts
@@ -0,0 +1,941 @@
+/**
+ * Terminal Host Daemon Client
+ *
+ * Client library for the Electron main process to communicate with
+ * the terminal host daemon. Handles:
+ * - Daemon lifecycle (spawning if not running)
+ * - Socket connection and reconnection
+ * - Request/response framing
+ * - Event streaming
+ */
+
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import {
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { connect, type Socket } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { app } from "electron";
+import {
+	type ClearScrollbackRequest,
+	type CreateOrAttachRequest,
+	type CreateOrAttachResponse,
+	type DetachRequest,
+	type EmptyResponse,
+	type HelloResponse,
+	type IpcErrorResponse,
+	type IpcEvent,
+	type IpcResponse,
+	type IpcSuccessResponse,
+	type KillAllRequest,
+	type KillRequest,
+	type ListSessionsResponse,
+	PROTOCOL_VERSION,
+	type ResizeRequest,
+	type ShutdownRequest,
+	type TerminalDataEvent,
+	type TerminalErrorEvent,
+	type TerminalExitEvent,
+	type WriteRequest,
+} from "./types";
+
+// =============================================================================
+// Connection State
+// =============================================================================
+
+enum ConnectionState {
+	DISCONNECTED = "disconnected",
+	CONNECTING = "connecting",
+	CONNECTED = "connected",
+}
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const SUPERSET_DIR_NAME =
+	process.env.NODE_ENV === "development" ? ".superset-dev" : ".superset";
+const SUPERSET_HOME_DIR = join(homedir(), SUPERSET_DIR_NAME);
+
+const SOCKET_PATH = join(SUPERSET_HOME_DIR, "terminal-host.sock");
+const TOKEN_PATH = join(SUPERSET_HOME_DIR, "terminal-host.token");
+const PID_PATH = join(SUPERSET_HOME_DIR, "terminal-host.pid");
+const SPAWN_LOCK_PATH = join(SUPERSET_HOME_DIR, "terminal-host.spawn.lock");
+
+// Connection timeouts
+const CONNECT_TIMEOUT_MS = 5000;
+const SPAWN_WAIT_MS = 2000;
+const REQUEST_TIMEOUT_MS = 30000;
+const SPAWN_LOCK_TIMEOUT_MS = 10000; // Max time to hold spawn lock
+
+// Queue limits
+const MAX_NOTIFY_QUEUE_BYTES = 2_000_000; // 2MB cap to prevent OOM
+
+// =============================================================================
+// NDJSON Parser
+// =============================================================================
+
+class NdjsonParser {
+	private remainder = "";
+
+	parse(chunk: string): Array<IpcResponse | IpcEvent> {
+		const messages: Array<IpcResponse | IpcEvent> = [];
+
+		// Prepend any remainder from previous parse
+		const data = this.remainder + chunk;
+		this.remainder = "";
+
+		let startIndex = 0;
+		let newlineIndex = data.indexOf("\n");
+
+		while (newlineIndex !== -1) {
+			const line = data.slice(startIndex, newlineIndex);
+
+			if (line.trim()) {
+				try {
+					messages.push(JSON.parse(line));
+				} catch {
+					console.warn("[TerminalHostClient] Failed to parse NDJSON line");
+				}
+			}
+
+			startIndex = newlineIndex + 1;
+			newlineIndex = data.indexOf("\n", startIndex);
+		}
+
+		// Save any remaining data after the last newline
+		if (startIndex < data.length) {
+			this.remainder = data.slice(startIndex);
+		}
+
+		return messages;
+	}
+}
+
+// =============================================================================
+// Pending Request Tracker
+// =============================================================================
+
+interface PendingRequest {
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	timeoutId: NodeJS.Timeout;
+}
+
+// =============================================================================
+// TerminalHostClient
+// =============================================================================
+
+export interface TerminalHostClientEvents {
+	data: (sessionId: string, data: string) => void;
+	exit: (sessionId: string, exitCode: number, signal?: number) => void;
+	/** Terminal-specific error (e.g., write queue full - paste dropped) */
+	terminalError: (sessionId: string, error: string, code?: string) => void;
+	connected: () => void;
+	disconnected: () => void;
+	error: (error: Error) => void;
+}
+
+/**
+ * Client for communicating with the terminal host daemon.
+ * Emits events for terminal data and exit.
+ */
+export class TerminalHostClient extends EventEmitter {
+	private socket: Socket | null = null;
+	private parser = new NdjsonParser();
+	private pendingRequests = new Map<string, PendingRequest>();
+	private requestCounter = 0;
+	private authenticated = false;
+	private connectionState = ConnectionState.DISCONNECTED;
+	private disposed = false;
+	private notifyQueue: string[] = [];
+	private notifyQueueBytes = 0;
+	private notifyDrainArmed = false;
+
+	// ===========================================================================
+	// Connection Management
+	// ===========================================================================
+
+	/**
+	 * Ensure we have a connected, authenticated socket.
+	 * Spawns daemon if needed.
+	 */
+	async ensureConnected(): Promise<void> {
+		// Already connected - fast path (no logging to avoid noise on every API call)
+		if (
+			this.connectionState === ConnectionState.CONNECTED &&
+			this.socket &&
+			this.authenticated
+		) {
+			return;
+		}
+
+		// Another connection in progress - wait with timeout
+		if (this.connectionState === ConnectionState.CONNECTING) {
+			console.log(
+				"[TerminalHostClient] Connection already in progress, waiting...",
+			);
+			return new Promise((resolve, reject) => {
+				const startTime = Date.now();
+				const WAIT_TIMEOUT_MS = 10000; // 10 seconds max wait
+
+				const checkConnection = () => {
+					if (
+						this.connectionState === ConnectionState.CONNECTED &&
+						this.socket &&
+						this.authenticated
+					) {
+						resolve();
+					} else if (this.connectionState === ConnectionState.DISCONNECTED) {
+						reject(new Error("Connection failed while waiting"));
+					} else if (Date.now() - startTime > WAIT_TIMEOUT_MS) {
+						reject(
+							new Error(
+								"Timeout waiting for connection - daemon may be unresponsive",
+							),
+						);
+					} else {
+						setTimeout(checkConnection, 100);
+					}
+				};
+				checkConnection();
+			});
+		}
+
+		this.connectionState = ConnectionState.CONNECTING;
+		console.log("[TerminalHostClient] Connecting to daemon...");
+
+		try {
+			// Try to connect to existing daemon
+			let connected = await this.tryConnect();
+			console.log(
+				`[TerminalHostClient] Initial connection attempt: ${connected ? "SUCCESS" : "FAILED"}`,
+			);
+
+			if (!connected) {
+				// Spawn daemon and retry
+				console.log("[TerminalHostClient] Spawning daemon...");
+				await this.spawnDaemon();
+				connected = await this.tryConnect();
+				console.log(
+					`[TerminalHostClient] Post-spawn connection attempt: ${connected ? "SUCCESS" : "FAILED"}`,
+				);
+
+				if (!connected) {
+					throw new Error("Failed to connect to daemon after spawn");
+				}
+			}
+
+			// Authenticate
+			console.log("[TerminalHostClient] Authenticating...");
+			await this.authenticate();
+			console.log("[TerminalHostClient] Authentication successful!");
+
+			this.connectionState = ConnectionState.CONNECTED;
+		} catch (error) {
+			this.connectionState = ConnectionState.DISCONNECTED;
+			throw error;
+		}
+	}
+
+	/**
+	 * Try to connect and authenticate to an existing daemon without spawning.
+	 * Returns true if successfully connected and authenticated, false if no daemon running.
+	 * This is useful for cleanup operations that should only act on existing daemons.
+	 */
+	async tryConnectAndAuthenticate(): Promise<boolean> {
+		// Already connected and authenticated
+		if (
+			this.connectionState === ConnectionState.CONNECTED &&
+			this.socket &&
+			this.authenticated
+		) {
+			return true;
+		}
+
+		// Don't interfere with an in-progress connection
+		if (this.connectionState === ConnectionState.CONNECTING) {
+			return false;
+		}
+
+		this.connectionState = ConnectionState.CONNECTING;
+
+		try {
+			const connected = await this.tryConnect();
+			if (!connected) {
+				this.connectionState = ConnectionState.DISCONNECTED;
+				return false;
+			}
+
+			await this.authenticate();
+			this.connectionState = ConnectionState.CONNECTED;
+			return true;
+		} catch {
+			this.connectionState = ConnectionState.DISCONNECTED;
+			return false;
+		}
+	}
+
+	/**
+	 * Try to connect to the daemon socket.
+	 * Returns true if connected, false if daemon not running.
+	 */
+	private async tryConnect(): Promise<boolean> {
+		return new Promise((resolve) => {
+			if (!existsSync(SOCKET_PATH)) {
+				resolve(false);
+				return;
+			}
+
+			const socket = connect(SOCKET_PATH);
+			let resolved = false;
+
+			const timeout = setTimeout(() => {
+				if (!resolved) {
+					resolved = true;
+					socket.destroy();
+					resolve(false);
+				}
+			}, CONNECT_TIMEOUT_MS);
+
+			socket.on("connect", () => {
+				if (!resolved) {
+					resolved = true;
+					clearTimeout(timeout);
+					this.socket = socket;
+					this.setupSocketHandlers();
+					resolve(true);
+				}
+			});
+
+			socket.on("error", () => {
+				if (!resolved) {
+					resolved = true;
+					clearTimeout(timeout);
+					resolve(false);
+				}
+			});
+		});
+	}
+
+	/**
+	 * Set up socket event handlers
+	 */
+	private setupSocketHandlers(): void {
+		if (!this.socket) return;
+
+		this.socket.setEncoding("utf-8");
+
+		this.socket.on("data", (data: string) => {
+			const messages = this.parser.parse(data);
+			for (const message of messages) {
+				this.handleMessage(message);
+			}
+		});
+
+		this.socket.on("drain", () => {
+			this.flushNotifyQueue();
+		});
+
+		this.socket.on("close", () => {
+			this.handleDisconnect();
+		});
+
+		this.socket.on("error", (error) => {
+			this.emit("error", error);
+			this.handleDisconnect();
+		});
+	}
+
+	/**
+	 * Handle incoming message (response or event)
+	 */
+	private handleMessage(message: IpcResponse | IpcEvent): void {
+		if ("id" in message) {
+			// Response to a request
+			const pending = this.pendingRequests.get(message.id);
+			if (pending) {
+				this.pendingRequests.delete(message.id);
+				clearTimeout(pending.timeoutId);
+
+				if (message.ok) {
+					pending.resolve((message as IpcSuccessResponse).payload);
+				} else {
+					const error = (message as IpcErrorResponse).error;
+					pending.reject(new Error(`${error.code}: ${error.message}`));
+				}
+			}
+		} else if (message.type === "event") {
+			// Event from daemon
+			const event = message as IpcEvent;
+			const payload = event.payload as
+				| TerminalDataEvent
+				| TerminalExitEvent
+				| TerminalErrorEvent;
+
+			if (payload.type === "data") {
+				this.emit("data", event.sessionId, (payload as TerminalDataEvent).data);
+			} else if (payload.type === "exit") {
+				const exitPayload = payload as TerminalExitEvent;
+				this.emit(
+					"exit",
+					event.sessionId,
+					exitPayload.exitCode,
+					exitPayload.signal,
+				);
+			} else if (payload.type === "error") {
+				const errorPayload = payload as TerminalErrorEvent;
+				// Emit terminal-specific error so callers can handle it
+				// This is critical for "Write queue full" - paste was silently dropped before!
+				this.emit(
+					"terminalError",
+					event.sessionId,
+					errorPayload.error,
+					errorPayload.code,
+				);
+			}
+		}
+	}
+
+	/**
+	 * Handle socket disconnect
+	 */
+	private handleDisconnect(): void {
+		this.socket = null;
+		this.authenticated = false;
+		this.connectionState = ConnectionState.DISCONNECTED;
+		this.notifyQueue = [];
+		this.notifyQueueBytes = 0;
+		this.notifyDrainArmed = false;
+
+		// Reject all pending requests
+		for (const [id, pending] of this.pendingRequests.entries()) {
+			clearTimeout(pending.timeoutId);
+			pending.reject(new Error("Connection lost"));
+			this.pendingRequests.delete(id);
+		}
+
+		this.emit("disconnected");
+	}
+
+	/**
+	 * Authenticate with the daemon
+	 */
+	private async authenticate(): Promise<void> {
+		if (!existsSync(TOKEN_PATH)) {
+			throw new Error("Auth token not found - daemon may not be running");
+		}
+
+		const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+
+		const response = (await this.sendRequest("hello", {
+			token,
+			protocolVersion: PROTOCOL_VERSION,
+		})) as HelloResponse;
+
+		if (response.protocolVersion !== PROTOCOL_VERSION) {
+			throw new Error(
+				`Protocol version mismatch: client=${PROTOCOL_VERSION}, daemon=${response.protocolVersion}`,
+			);
+		}
+
+		this.authenticated = true;
+		this.emit("connected");
+	}
+
+	// ===========================================================================
+	// Daemon Spawning
+	// ===========================================================================
+
+	/**
+	 * Check if there's an active daemon listening on the socket.
+	 * Returns true if socket is live and responding.
+	 */
+	private isSocketLive(): Promise<boolean> {
+		return new Promise((resolve) => {
+			if (!existsSync(SOCKET_PATH)) {
+				resolve(false);
+				return;
+			}
+
+			const testSocket = connect(SOCKET_PATH);
+			const timeout = setTimeout(() => {
+				testSocket.destroy();
+				resolve(false);
+			}, 1000);
+
+			testSocket.on("connect", () => {
+				clearTimeout(timeout);
+				testSocket.destroy();
+				resolve(true);
+			});
+
+			testSocket.on("error", () => {
+				clearTimeout(timeout);
+				resolve(false);
+			});
+		});
+	}
+
+	/**
+	 * Acquire spawn lock to prevent concurrent daemon spawns.
+	 * Returns true if lock acquired, false if another spawn is in progress.
+	 */
+	private acquireSpawnLock(): boolean {
+		try {
+			// Ensure superset home directory exists before any file operations
+			if (!existsSync(SUPERSET_HOME_DIR)) {
+				mkdirSync(SUPERSET_HOME_DIR, { recursive: true, mode: 0o700 });
+			}
+
+			// Check if lock exists and is recent (within timeout)
+			if (existsSync(SPAWN_LOCK_PATH)) {
+				const lockContent = readFileSync(SPAWN_LOCK_PATH, "utf-8").trim();
+				const lockTime = Number.parseInt(lockContent, 10);
+				if (
+					!Number.isNaN(lockTime) &&
+					Date.now() - lockTime < SPAWN_LOCK_TIMEOUT_MS
+				) {
+					// Lock is held by another process
+					return false;
+				}
+				// Stale lock, remove it
+				unlinkSync(SPAWN_LOCK_PATH);
+			}
+
+			// Create lock file with current timestamp
+			writeFileSync(SPAWN_LOCK_PATH, String(Date.now()), { mode: 0o600 });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Release spawn lock
+	 */
+	private releaseSpawnLock(): void {
+		try {
+			if (existsSync(SPAWN_LOCK_PATH)) {
+				unlinkSync(SPAWN_LOCK_PATH);
+			}
+		} catch {
+			// Best effort cleanup
+		}
+	}
+
+	/**
+	 * Spawn the daemon process if not running
+	 */
+	private async spawnDaemon(): Promise<void> {
+		// Check if socket is live first - this is the authoritative check
+		// PID file can be stale if daemon crashed and PID was reused by another process
+		if (existsSync(SOCKET_PATH)) {
+			const isLive = await this.isSocketLive();
+			if (isLive) {
+				console.log("[TerminalHostClient] Socket is live, daemon is running");
+				return;
+			}
+
+			// Socket exists but not responsive - safe to remove
+			console.log("[TerminalHostClient] Removing stale socket file");
+			try {
+				unlinkSync(SOCKET_PATH);
+			} catch {
+				// Ignore - might not have permission
+			}
+		}
+
+		// Also clean up stale PID file if socket was not live
+		// This handles the case where daemon crashed and PID was reused
+		if (existsSync(PID_PATH)) {
+			console.log("[TerminalHostClient] Removing stale PID file");
+			try {
+				unlinkSync(PID_PATH);
+			} catch {
+				// Ignore - might not have permission
+			}
+		}
+
+		// Acquire spawn lock to prevent concurrent spawns
+		if (!this.acquireSpawnLock()) {
+			console.log("[TerminalHostClient] Another spawn in progress, waiting...");
+			// Wait for the other spawn to complete
+			await this.waitForDaemon();
+			return;
+		}
+
+		try {
+			// Get path to daemon script
+			const daemonScript = this.getDaemonScriptPath();
+			console.log(`[TerminalHostClient] Daemon script path: ${daemonScript}`);
+			console.log(
+				`[TerminalHostClient] Script exists: ${existsSync(daemonScript)}`,
+			);
+
+			if (!existsSync(daemonScript)) {
+				throw new Error(`Daemon script not found: ${daemonScript}`);
+			}
+
+			console.log(
+				`[TerminalHostClient] Spawning daemon with execPath: ${process.execPath}`,
+			);
+
+			// Open log file for daemon output (helps debug daemon-side issues)
+			const logPath = join(SUPERSET_HOME_DIR, "daemon.log");
+			let logFd: number;
+			try {
+				logFd = openSync(logPath, "a");
+			} catch (error) {
+				console.warn(
+					`[TerminalHostClient] Failed to open daemon log file: ${error}`,
+				);
+				// Fall back to ignoring output if we can't open log file
+				logFd = -1;
+			}
+
+			// Spawn daemon as detached process
+			const child = spawn(process.execPath, [daemonScript], {
+				detached: true,
+				stdio: logFd >= 0 ? ["ignore", logFd, logFd] : "ignore",
+				env: {
+					...process.env,
+					ELECTRON_RUN_AS_NODE: "1",
+					NODE_ENV: process.env.NODE_ENV,
+				},
+			});
+
+			console.log(`[TerminalHostClient] Daemon spawned with PID: ${child.pid}`);
+
+			// Unref to allow parent to exit independently
+			child.unref();
+
+			// Wait for daemon to start
+			console.log("[TerminalHostClient] Waiting for daemon to start...");
+			await this.waitForDaemon();
+			console.log("[TerminalHostClient] Daemon started successfully");
+		} finally {
+			this.releaseSpawnLock();
+		}
+	}
+
+	/**
+	 * Get path to daemon script
+	 */
+	private getDaemonScriptPath(): string {
+		if (app.isPackaged) {
+			// Production: script is in app resources
+			return join(app.getAppPath(), "dist", "main", "terminal-host.js");
+		}
+
+		// Development: electron-vite outputs to dist/main/
+		const appPath = app.getAppPath();
+		return join(appPath, "dist", "main", "terminal-host.js");
+	}
+
+	/**
+	 * Wait for daemon to be ready
+	 */
+	private async waitForDaemon(): Promise<void> {
+		const startTime = Date.now();
+
+		while (Date.now() - startTime < SPAWN_WAIT_MS) {
+			if (existsSync(SOCKET_PATH)) {
+				// Give it a moment to start listening
+				await this.sleep(200);
+				return;
+			}
+			await this.sleep(100);
+		}
+
+		throw new Error("Daemon failed to start in time");
+	}
+
+	private sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+
+	// ===========================================================================
+	// Request/Response
+	// ===========================================================================
+
+	/**
+	 * Send a request to the daemon and wait for response
+	 */
+	private sendRequest(type: string, payload: unknown): Promise<unknown> {
+		return new Promise((resolve, reject) => {
+			if (!this.socket) {
+				reject(new Error("Not connected"));
+				return;
+			}
+
+			const id = `req_${++this.requestCounter}`;
+
+			const timeoutId = setTimeout(() => {
+				this.pendingRequests.delete(id);
+				reject(new Error(`Request timeout: ${type}`));
+			}, REQUEST_TIMEOUT_MS);
+
+			this.pendingRequests.set(id, { resolve, reject, timeoutId });
+
+			const message = `${JSON.stringify({ id, type, payload })}\n`;
+			this.socket.write(message);
+		});
+	}
+
+	/**
+	 * Send a notification (no pending request / no timeout).
+	 *
+	 * Used for high-frequency messages like terminal input, where request/response
+	 * overhead can cause timeouts under load and drop data. The daemon may still
+	 * send a response for compatibility, but this client will ignore it.
+	 *
+	 * Returns false if queue is full (caller should handle).
+	 */
+	private sendNotification(type: string, payload: unknown): boolean {
+		if (!this.socket) return false;
+
+		const id = `notify_${++this.requestCounter}`;
+		const message = `${JSON.stringify({ id, type, payload })}\n`;
+		const messageBytes = Buffer.byteLength(message, "utf8");
+
+		// Check queue limit to prevent OOM under backpressure
+		if (this.notifyQueueBytes + messageBytes > MAX_NOTIFY_QUEUE_BYTES) {
+			return false;
+		}
+
+		// If we're already backpressured, just queue.
+		if (this.notifyDrainArmed || this.notifyQueue.length > 0) {
+			this.notifyQueue.push(message);
+			this.notifyQueueBytes += messageBytes;
+			return true;
+		}
+
+		const canWrite = this.socket.write(message);
+		if (!canWrite) {
+			// Message is queued internally by the socket; arm drain to flush any
+			// subsequent notifications we enqueue.
+			this.notifyDrainArmed = true;
+		}
+		return true;
+	}
+
+	private flushNotifyQueue(): void {
+		if (!this.socket) return;
+		if (!this.notifyDrainArmed && this.notifyQueue.length === 0) return;
+
+		this.notifyDrainArmed = false;
+
+		while (this.notifyQueue.length > 0) {
+			const message = this.notifyQueue.shift();
+			if (!message) break;
+			this.notifyQueueBytes -= Buffer.byteLength(message, "utf8");
+
+			const canWrite = this.socket.write(message);
+			if (!canWrite) {
+				this.notifyDrainArmed = true;
+				return;
+			}
+		}
+	}
+
+	// ===========================================================================
+	// Public API
+	// ===========================================================================
+
+	/**
+	 * Create or attach to a terminal session
+	 */
+	async createOrAttach(
+		request: CreateOrAttachRequest,
+	): Promise<CreateOrAttachResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest(
+			"createOrAttach",
+			request,
+		)) as CreateOrAttachResponse;
+	}
+
+	/**
+	 * Write data to a terminal session
+	 */
+	async write(request: WriteRequest): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest("write", request)) as EmptyResponse;
+	}
+
+	/**
+	 * Write data without waiting for a response (best-effort, backpressured).
+	 * Prevents large pastes from timing out and dropping chunks when the daemon
+	 * is busy processing output.
+	 */
+	writeNoAck(request: WriteRequest): void {
+		void this.ensureConnected()
+			.then(() => {
+				const sent = this.sendNotification("write", request);
+				if (!sent) {
+					// Queue full - notify the session so it can surface the error to the user
+					this.emit(
+						"terminalError",
+						request.sessionId,
+						"Write queue full - input dropped",
+						"QUEUE_FULL",
+					);
+				}
+			})
+			.catch((error) => {
+				this.emit(
+					"error",
+					error instanceof Error ? error : new Error(String(error)),
+				);
+			});
+	}
+
+	/**
+	 * Resize a terminal session
+	 */
+	async resize(request: ResizeRequest): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest("resize", request)) as EmptyResponse;
+	}
+
+	/**
+	 * Detach from a terminal session
+	 */
+	async detach(request: DetachRequest): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest("detach", request)) as EmptyResponse;
+	}
+
+	/**
+	 * Kill a terminal session
+	 */
+	async kill(request: KillRequest): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest("kill", request)) as EmptyResponse;
+	}
+
+	/**
+	 * Kill all terminal sessions
+	 */
+	async killAll(request: KillAllRequest): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest("killAll", request)) as EmptyResponse;
+	}
+
+	/**
+	 * List all sessions
+	 */
+	async listSessions(): Promise<ListSessionsResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest(
+			"listSessions",
+			undefined,
+		)) as ListSessionsResponse;
+	}
+
+	/**
+	 * Clear scrollback for a session
+	 */
+	async clearScrollback(
+		request: ClearScrollbackRequest,
+	): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		return (await this.sendRequest(
+			"clearScrollback",
+			request,
+		)) as EmptyResponse;
+	}
+
+	/**
+	 * Shutdown the daemon gracefully.
+	 * After calling this, the client should be disposed and a new daemon
+	 * will be spawned on the next getTerminalHostClient() call.
+	 */
+	async shutdown(request: ShutdownRequest = {}): Promise<EmptyResponse> {
+		await this.ensureConnected();
+		const response = (await this.sendRequest(
+			"shutdown",
+			request,
+		)) as EmptyResponse;
+		// Disconnect after shutdown request is sent
+		this.disconnect();
+		return response;
+	}
+
+	/**
+	 * Shutdown the daemon if it's currently running, without spawning a new one.
+	 * Returns true if daemon was running and shutdown was sent, false if no daemon was running.
+	 * This is useful for cleanup operations that should only affect existing daemons.
+	 */
+	async shutdownIfRunning(
+		request: ShutdownRequest = {},
+	): Promise<{ wasRunning: boolean }> {
+		const connected = await this.tryConnectAndAuthenticate();
+		if (!connected) {
+			return { wasRunning: false };
+		}
+
+		try {
+			await this.sendRequest("shutdown", request);
+		} finally {
+			this.disconnect();
+		}
+		return { wasRunning: true };
+	}
+
+	/**
+	 * Disconnect from daemon (but don't stop it)
+	 */
+	disconnect(): void {
+		if (this.socket) {
+			this.socket.destroy();
+			this.socket = null;
+		}
+		this.authenticated = false;
+		this.connectionState = ConnectionState.DISCONNECTED;
+	}
+
+	/**
+	 * Dispose of the client
+	 */
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.disconnect();
+		this.removeAllListeners();
+	}
+}
+
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+
+let clientInstance: TerminalHostClient | null = null;
+
+/**
+ * Get the singleton terminal host client instance
+ */
+export function getTerminalHostClient(): TerminalHostClient {
+	if (!clientInstance) {
+		clientInstance = new TerminalHostClient();
+	}
+	return clientInstance;
+}
+
+/**
+ * Dispose of the singleton client
+ */
+export function disposeTerminalHostClient(): void {
+	if (clientInstance) {
+		clientInstance.dispose();
+		clientInstance = null;
+	}
+}
diff --git a/apps/desktop/src/main/lib/terminal-host/headless-emulator.ts b/apps/desktop/src/main/lib/terminal-host/headless-emulator.ts
new file mode 100644
index 00000000000..02522ad4f54
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal-host/headless-emulator.ts
@@ -0,0 +1,606 @@
+/**
+ * Headless Terminal Emulator
+ *
+ * Wraps @xterm/headless with:
+ * - Mode tracking (DECSET/DECRST parsing)
+ * - Snapshot generation via @xterm/addon-serialize
+ * - Rehydration sequence generation for mode restoration
+ */
+
+import { SerializeAddon } from "@xterm/addon-serialize";
+import { Terminal } from "@xterm/headless";
+import {
+	DEFAULT_MODES,
+	type TerminalModes,
+	type TerminalSnapshot,
+} from "./types";
+
+// =============================================================================
+// Mode Tracking Constants
+// =============================================================================
+
+// Escape character
+const ESC = "\x1b";
+const BEL = "\x07";
+
+const DEBUG_EMULATOR_TIMING =
+	process.env.SUPERSET_TERMINAL_EMULATOR_DEBUG === "1";
+
+/**
+ * DECSET/DECRST mode numbers we track
+ */
+const MODE_MAP: Record<number, keyof TerminalModes> = {
+	1: "applicationCursorKeys",
+	6: "originMode",
+	7: "autoWrap",
+	9: "mouseTrackingX10",
+	25: "cursorVisible",
+	47: "alternateScreen", // Legacy alternate screen
+	1000: "mouseTrackingNormal",
+	1001: "mouseTrackingHighlight",
+	1002: "mouseTrackingButtonEvent",
+	1003: "mouseTrackingAnyEvent",
+	1004: "focusReporting",
+	1005: "mouseUtf8",
+	1006: "mouseSgr",
+	1049: "alternateScreen", // Modern alternate screen with save/restore
+	2004: "bracketedPaste",
+};
+
+// =============================================================================
+// Headless Emulator Class
+// =============================================================================
+
+export interface HeadlessEmulatorOptions {
+	cols?: number;
+	rows?: number;
+	scrollback?: number;
+}
+
+export class HeadlessEmulator {
+	private terminal: Terminal;
+	private serializeAddon: SerializeAddon;
+	private modes: TerminalModes;
+	private cwd: string | null = null;
+	private disposed = false;
+
+	// Pending output buffer for query responses
+	private pendingOutput: string[] = [];
+	private onDataCallback?: (data: string) => void;
+
+	// Buffer for partial escape sequences that span chunk boundaries
+	private escapeSequenceBuffer = "";
+
+	// Maximum buffer size to prevent unbounded growth (safety cap)
+	private static readonly MAX_ESCAPE_BUFFER_SIZE = 1024;
+
+	constructor(options: HeadlessEmulatorOptions = {}) {
+		const { cols = 80, rows = 24, scrollback = 10000 } = options;
+
+		this.terminal = new Terminal({
+			cols,
+			rows,
+			scrollback,
+			allowProposedApi: true,
+		});
+
+		this.serializeAddon = new SerializeAddon();
+		this.terminal.loadAddon(this.serializeAddon);
+
+		// Initialize mode state
+		this.modes = { ...DEFAULT_MODES };
+
+		// Listen for terminal output (query responses)
+		this.terminal.onData((data) => {
+			this.pendingOutput.push(data);
+			this.onDataCallback?.(data);
+		});
+	}
+
+	/**
+	 * Set callback for terminal-generated output (query responses)
+	 */
+	onData(callback: (data: string) => void): void {
+		this.onDataCallback = callback;
+	}
+
+	/**
+	 * Get and clear pending output (query responses)
+	 */
+	flushPendingOutput(): string[] {
+		const output = this.pendingOutput;
+		this.pendingOutput = [];
+		return output;
+	}
+
+	/**
+	 * Write data to the terminal emulator (synchronous, non-blocking)
+	 * Data is buffered and will be processed asynchronously.
+	 * Use writeSync() if you need to wait for the write to complete.
+	 */
+	write(data: string): void {
+		if (this.disposed) return;
+
+		if (!DEBUG_EMULATOR_TIMING) {
+			// Parse escape sequences with chunk-safe buffering
+			this.parseEscapeSequences(data);
+			// Write to headless terminal (buffered/async)
+			this.terminal.write(data);
+			return;
+		}
+
+		const parseStart = performance.now();
+		this.parseEscapeSequences(data);
+		const parseTime = performance.now() - parseStart;
+
+		const terminalStart = performance.now();
+		this.terminal.write(data);
+		const terminalTime = performance.now() - terminalStart;
+
+		if (parseTime > 2 || terminalTime > 2) {
+			console.warn(
+				`[HeadlessEmulator] write(${data.length}b): parse=${parseTime.toFixed(1)}ms, terminal=${terminalTime.toFixed(1)}ms`,
+			);
+		}
+	}
+
+	/**
+	 * Write data to the terminal emulator and wait for completion.
+	 * Use this when you need to ensure data is processed before reading state.
+	 */
+	async writeSync(data: string): Promise<void> {
+		if (this.disposed) return;
+
+		// Parse escape sequences with chunk-safe buffering
+		this.parseEscapeSequences(data);
+
+		// Write to headless terminal and wait for completion
+		return new Promise<void>((resolve) => {
+			this.terminal.write(data, () => resolve());
+		});
+	}
+
+	/**
+	 * Resize the terminal
+	 */
+	resize(cols: number, rows: number): void {
+		if (this.disposed) return;
+		this.terminal.resize(cols, rows);
+	}
+
+	/**
+	 * Get current terminal dimensions
+	 */
+	getDimensions(): { cols: number; rows: number } {
+		return {
+			cols: this.terminal.cols,
+			rows: this.terminal.rows,
+		};
+	}
+
+	/**
+	 * Get current terminal modes
+	 */
+	getModes(): TerminalModes {
+		return { ...this.modes };
+	}
+
+	/**
+	 * Get current working directory (from OSC-7)
+	 */
+	getCwd(): string | null {
+		return this.cwd;
+	}
+
+	/**
+	 * Set CWD directly (for initial session setup)
+	 */
+	setCwd(cwd: string): void {
+		this.cwd = cwd;
+	}
+
+	/**
+	 * Get scrollback line count
+	 */
+	getScrollbackLines(): number {
+		return this.terminal.buffer.active.length;
+	}
+
+	/**
+	 * Flush all pending writes to the terminal.
+	 * Call this before getSnapshot() if you've written data without waiting.
+	 */
+	async flush(): Promise<void> {
+		if (this.disposed) return;
+		// Write an empty string with callback to ensure all pending writes are processed
+		return new Promise<void>((resolve) => {
+			this.terminal.write("", () => resolve());
+		});
+	}
+
+	/**
+	 * Generate a complete snapshot for session restore.
+	 * Note: Call flush() first if you have pending async writes.
+	 */
+	getSnapshot(): TerminalSnapshot {
+		const snapshotAnsi = this.serializeAddon.serialize({
+			scrollback: this.terminal.options.scrollback ?? 10000,
+		});
+
+		const rehydrateSequences = this.generateRehydrateSequences();
+
+		// Build debug diagnostics
+		const xtermBufferType = this.terminal.buffer.active.type;
+		const hasAltScreenEntry = snapshotAnsi.includes("\x1b[?1049h");
+
+		let altBufferDebug:
+			| {
+					lines: number;
+					nonEmptyLines: number;
+					totalChars: number;
+					cursorX: number;
+					cursorY: number;
+					sampleLines: string[];
+			  }
+			| undefined;
+
+		if (this.modes.alternateScreen || xtermBufferType === "alternate") {
+			const altBuffer = this.terminal.buffer.alternate;
+			let nonEmptyLines = 0;
+			let totalChars = 0;
+			const sampleLines: string[] = [];
+
+			for (let i = 0; i < altBuffer.length; i++) {
+				const line = altBuffer.getLine(i);
+				if (line) {
+					const lineText = line.translateToString(true);
+					if (lineText.trim().length > 0) {
+						nonEmptyLines++;
+						totalChars += lineText.length;
+						if (sampleLines.length < 3) {
+							sampleLines.push(lineText.slice(0, 80));
+						}
+					}
+				}
+			}
+
+			altBufferDebug = {
+				lines: altBuffer.length,
+				nonEmptyLines,
+				totalChars,
+				cursorX: altBuffer.cursorX,
+				cursorY: altBuffer.cursorY,
+				sampleLines,
+			};
+		}
+
+		return {
+			snapshotAnsi,
+			rehydrateSequences,
+			cwd: this.cwd,
+			modes: { ...this.modes },
+			cols: this.terminal.cols,
+			rows: this.terminal.rows,
+			scrollbackLines: this.getScrollbackLines(),
+			debug: {
+				xtermBufferType,
+				hasAltScreenEntry,
+				altBuffer: altBufferDebug,
+				normalBufferLines: this.terminal.buffer.normal.length,
+			},
+		};
+	}
+
+	/**
+	 * Generate a complete snapshot after flushing pending writes.
+	 * This is the preferred method for getting consistent snapshots.
+	 */
+	async getSnapshotAsync(): Promise<TerminalSnapshot> {
+		await this.flush();
+		return this.getSnapshot();
+	}
+
+	/**
+	 * Clear terminal buffer
+	 */
+	clear(): void {
+		if (this.disposed) return;
+		this.terminal.clear();
+	}
+
+	/**
+	 * Reset terminal to default state
+	 */
+	reset(): void {
+		if (this.disposed) return;
+		this.terminal.reset();
+		this.modes = { ...DEFAULT_MODES };
+	}
+
+	/**
+	 * Dispose of the terminal
+	 */
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.terminal.dispose();
+	}
+
+	// ===========================================================================
+	// Private Methods
+	// ===========================================================================
+
+	/**
+	 * Parse escape sequences with chunk-safe buffering.
+	 * PTY output can split sequences across chunks, so we buffer partial sequences.
+	 *
+	 * IMPORTANT: We only buffer sequences we actually track (DECSET/DECRST and OSC-7).
+	 * Other escape sequences (colors, cursor moves, etc.) are NOT buffered to prevent
+	 * memory leaks from unbounded buffer growth.
+	 */
+	private parseEscapeSequences(data: string): void {
+		// Prepend any buffered partial sequence from previous chunk
+		const fullData = this.escapeSequenceBuffer + data;
+		this.escapeSequenceBuffer = "";
+
+		// Parse complete sequences in the data
+		this.parseModeChanges(fullData);
+		this.parseOsc7(fullData);
+
+		// Check for incomplete sequences we care about at the end
+		// We only buffer DECSET/DECRST (ESC[?...) and OSC-7 (ESC]7;...)
+		const incompleteSequence = this.findIncompleteTrackedSequence(fullData);
+
+		if (incompleteSequence) {
+			// Cap buffer size to prevent unbounded growth
+			if (
+				incompleteSequence.length <= HeadlessEmulator.MAX_ESCAPE_BUFFER_SIZE
+			) {
+				this.escapeSequenceBuffer = incompleteSequence;
+			}
+			// If buffer too large, just discard it (likely malformed or attack)
+		}
+	}
+
+	/**
+	 * Find an incomplete DECSET/DECRST or OSC-7 sequence at the end of data.
+	 * Returns the incomplete sequence string, or null if none found.
+	 *
+	 * We ONLY buffer sequences we track:
+	 * - DECSET/DECRST: ESC[?...h or ESC[?...l
+	 * - OSC-7: ESC]7;...BEL or ESC]7;...ESC\
+	 *
+	 * Other CSI sequences (ESC[31m, ESC[H, etc.) are NOT buffered.
+	 */
+	private findIncompleteTrackedSequence(data: string): string | null {
+		const escEscaped = escapeRegex(ESC);
+
+		// Look for potential incomplete sequences from the end
+		const lastEscIndex = data.lastIndexOf(ESC);
+		if (lastEscIndex === -1) return null;
+
+		const afterLastEsc = data.slice(lastEscIndex);
+
+		// Check if this looks like a sequence we track
+
+		// Pattern: ESC[? - start of DECSET/DECRST
+		if (afterLastEsc.startsWith(`${ESC}[?`)) {
+			// Check if it's complete (ends with h or l after digits)
+			const completePattern = new RegExp(`${escEscaped}\\[\\?[0-9;]+[hl]`);
+			if (completePattern.test(afterLastEsc)) {
+				// Complete DECSET/DECRST - check if there's another incomplete after
+				const globalPattern = new RegExp(`${escEscaped}\\[\\?[0-9;]+[hl]`, "g");
+				const matches = afterLastEsc.match(globalPattern);
+				if (matches) {
+					const lastMatch = matches[matches.length - 1];
+					const lastMatchEnd =
+						afterLastEsc.lastIndexOf(lastMatch) + lastMatch.length;
+					const remainder = afterLastEsc.slice(lastMatchEnd);
+					if (remainder.includes(ESC)) {
+						return this.findIncompleteTrackedSequence(remainder);
+					}
+				}
+				return null; // Complete
+			}
+			// Incomplete DECSET/DECRST - buffer it
+			return afterLastEsc;
+		}
+
+		// Pattern: ESC]7; - start of OSC-7
+		if (afterLastEsc.startsWith(`${ESC}]7;`)) {
+			// Check if it's complete (ends with BEL or ESC\)
+			if (afterLastEsc.includes(BEL) || afterLastEsc.includes(`${ESC}\\`)) {
+				return null; // Complete
+			}
+			// Incomplete OSC-7 - buffer it
+			return afterLastEsc;
+		}
+
+		// Check for partial starts of tracked sequences
+		// These could become tracked sequences with more data
+		if (afterLastEsc === ESC) return afterLastEsc; // Just ESC
+		if (afterLastEsc === `${ESC}[`) return afterLastEsc; // ESC[
+		if (afterLastEsc === `${ESC}]`) return afterLastEsc; // ESC]
+		if (afterLastEsc === `${ESC}]7`) return afterLastEsc; // ESC]7
+		const incompleteDecset = new RegExp(`^${escEscaped}\\[\\?[0-9;]*$`);
+		if (incompleteDecset.test(afterLastEsc)) return afterLastEsc; // ESC[?123
+
+		// Not a sequence we track (e.g., ESC[31m, ESC[H) - don't buffer
+		return null;
+	}
+
+	/**
+	 * Parse DECSET/DECRST sequences from terminal data
+	 */
+	private parseModeChanges(data: string): void {
+		// Match CSI ? Pm h (DECSET) and CSI ? Pm l (DECRST)
+		// Examples: ESC[?1h (enable app cursor), ESC[?2004l (disable bracketed paste)
+		// Also handles multiple modes: ESC[?1;2004h
+		// Using string-based regex to avoid control character linter errors
+		const modeRegex = new RegExp(
+			`${escapeRegex(ESC)}\\[\\?([0-9;]+)([hl])`,
+			"g",
+		);
+
+		for (const match of data.matchAll(modeRegex)) {
+			const modesStr = match[1];
+			const action = match[2]; // 'h' = set (enable), 'l' = reset (disable)
+			const enable = action === "h";
+
+			// Split on semicolons for multiple modes
+			const modeNumbers = modesStr
+				.split(";")
+				.map((s) => Number.parseInt(s, 10));
+
+			for (const modeNum of modeNumbers) {
+				const modeName = MODE_MAP[modeNum];
+				if (modeName) {
+					// For cursor visibility and auto-wrap, 'h' means true, 'l' means false
+					// But their defaults are different (cursorVisible=true, autoWrap=true)
+					this.modes[modeName] = enable;
+				}
+			}
+		}
+	}
+
+	/**
+	 * Parse OSC-7 sequences for CWD tracking
+	 * Format: ESC]7;file://hostname/path BEL or ESC]7;file://hostname/path ESC\
+	 *
+	 * The path part starts after the hostname (after file://hostname).
+	 * Hostname can be empty, localhost, or a machine name.
+	 */
+	private parseOsc7(data: string): void {
+		// OSC-7 format: \x1b]7;file://hostname/path\x07
+		// We need to extract the /path portion after the hostname
+		// Hostname ends at the first / after file://
+
+		// Pattern explanation:
+		// - ESC ]7;file:// - the OSC-7 prefix
+		// - [^/]* - the hostname (anything that's not a slash)
+		// - (/.+?) - capture the path (starts with /, non-greedy)
+		// - (?:BEL|ESC\\) - terminated by BEL or ST
+
+		// Using string building to avoid control character linter issues
+		const escEscaped = escapeRegex(ESC);
+		const belEscaped = escapeRegex(BEL);
+
+		// Match OSC-7 with either terminator
+		const osc7Pattern = `${escEscaped}\\]7;file://[^/]*(/.+?)(?:${belEscaped}|${escEscaped}\\\\)`;
+		const osc7Regex = new RegExp(osc7Pattern, "g");
+
+		for (const match of data.matchAll(osc7Regex)) {
+			if (match[1]) {
+				try {
+					this.cwd = decodeURIComponent(match[1]);
+				} catch {
+					// If decoding fails, use the raw path
+					this.cwd = match[1];
+				}
+			}
+		}
+	}
+
+	/**
+	 * Generate escape sequences to restore current mode state
+	 * These sequences should be written to a fresh xterm instance before
+	 * writing the snapshot to ensure input behavior matches.
+	 */
+	private generateRehydrateSequences(): string {
+		const sequences: string[] = [];
+
+		// Helper to add DECSET/DECRST sequence
+		const addModeSequence = (
+			modeNum: number,
+			enabled: boolean,
+			defaultEnabled: boolean,
+		) => {
+			// Only add sequence if different from default
+			if (enabled !== defaultEnabled) {
+				sequences.push(`${ESC}[?${modeNum}${enabled ? "h" : "l"}`);
+			}
+		};
+
+		// Application cursor keys (mode 1)
+		addModeSequence(1, this.modes.applicationCursorKeys, false);
+
+		// Origin mode (mode 6)
+		addModeSequence(6, this.modes.originMode, false);
+
+		// Auto-wrap mode (mode 7)
+		addModeSequence(7, this.modes.autoWrap, true);
+
+		// Cursor visibility (mode 25)
+		addModeSequence(25, this.modes.cursorVisible, true);
+
+		// Mouse tracking modes (mutually exclusive typically, but we track all)
+		addModeSequence(9, this.modes.mouseTrackingX10, false);
+		addModeSequence(1000, this.modes.mouseTrackingNormal, false);
+		addModeSequence(1001, this.modes.mouseTrackingHighlight, false);
+		addModeSequence(1002, this.modes.mouseTrackingButtonEvent, false);
+		addModeSequence(1003, this.modes.mouseTrackingAnyEvent, false);
+
+		// Mouse encoding modes
+		addModeSequence(1005, this.modes.mouseUtf8, false);
+		addModeSequence(1006, this.modes.mouseSgr, false);
+
+		// Focus reporting (mode 1004)
+		addModeSequence(1004, this.modes.focusReporting, false);
+
+		// Bracketed paste (mode 2004)
+		addModeSequence(2004, this.modes.bracketedPaste, false);
+
+		// Note: We don't restore alternate screen mode (1049/47) here because
+		// the serialized snapshot already contains the correct screen buffer.
+		// Restoring it would cause incorrect behavior.
+
+		return sequences.join("");
+	}
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Apply a snapshot to a headless emulator (for testing round-trip)
+ */
+export function applySnapshot(
+	emulator: HeadlessEmulator,
+	snapshot: TerminalSnapshot,
+): void {
+	// First, write the rehydrate sequences to restore mode state
+	emulator.write(snapshot.rehydrateSequences);
+
+	// Then write the serialized screen content
+	emulator.write(snapshot.snapshotAnsi);
+}
+
+/**
+ * Compare two mode states for equality
+ */
+export function modesEqual(a: TerminalModes, b: TerminalModes): boolean {
+	return (
+		a.applicationCursorKeys === b.applicationCursorKeys &&
+		a.bracketedPaste === b.bracketedPaste &&
+		a.mouseTrackingX10 === b.mouseTrackingX10 &&
+		a.mouseTrackingNormal === b.mouseTrackingNormal &&
+		a.mouseTrackingHighlight === b.mouseTrackingHighlight &&
+		a.mouseTrackingButtonEvent === b.mouseTrackingButtonEvent &&
+		a.mouseTrackingAnyEvent === b.mouseTrackingAnyEvent &&
+		a.focusReporting === b.focusReporting &&
+		a.mouseUtf8 === b.mouseUtf8 &&
+		a.mouseSgr === b.mouseSgr &&
+		a.alternateScreen === b.alternateScreen &&
+		a.cursorVisible === b.cursorVisible &&
+		a.originMode === b.originMode &&
+		a.autoWrap === b.autoWrap
+	);
+}
diff --git a/apps/desktop/src/main/lib/terminal-host/types.ts b/apps/desktop/src/main/lib/terminal-host/types.ts
new file mode 100644
index 00000000000..877e7962db5
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal-host/types.ts
@@ -0,0 +1,343 @@
+/**
+ * Terminal Host Daemon Protocol Types
+ *
+ * This file defines the IPC protocol between the Electron main process
+ * and the terminal host daemon. Changes must be additive-only for
+ * backwards compatibility.
+ */
+
+// Protocol version - increment for breaking changes
+export const PROTOCOL_VERSION = 1;
+
+// =============================================================================
+// Mode Tracking
+// =============================================================================
+
+/**
+ * Terminal modes that affect input behavior and must be restored on attach.
+ * These correspond to DECSET/DECRST (CSI ? Pm h/l) escape sequences.
+ */
+export interface TerminalModes {
+	/** DECCKM - Application cursor keys (mode 1) */
+	applicationCursorKeys: boolean;
+	/** Bracketed paste mode (mode 2004) */
+	bracketedPaste: boolean;
+	/** X10 mouse tracking (mode 9) */
+	mouseTrackingX10: boolean;
+	/** Normal mouse tracking - button events (mode 1000) */
+	mouseTrackingNormal: boolean;
+	/** Highlight mouse tracking (mode 1001) */
+	mouseTrackingHighlight: boolean;
+	/** Button-event mouse tracking (mode 1002) */
+	mouseTrackingButtonEvent: boolean;
+	/** Any-event mouse tracking (mode 1003) */
+	mouseTrackingAnyEvent: boolean;
+	/** Focus reporting (mode 1004) */
+	focusReporting: boolean;
+	/** UTF-8 mouse mode (mode 1005) */
+	mouseUtf8: boolean;
+	/** SGR mouse mode (mode 1006) */
+	mouseSgr: boolean;
+	/** Alternate screen buffer (mode 1049 or 47) */
+	alternateScreen: boolean;
+	/** Cursor visibility (mode 25) */
+	cursorVisible: boolean;
+	/** Origin mode (mode 6) */
+	originMode: boolean;
+	/** Auto-wrap mode (mode 7) */
+	autoWrap: boolean;
+}
+
+/**
+ * Default terminal modes (standard terminal state)
+ */
+export const DEFAULT_MODES: TerminalModes = {
+	applicationCursorKeys: false,
+	bracketedPaste: false,
+	mouseTrackingX10: false,
+	mouseTrackingNormal: false,
+	mouseTrackingHighlight: false,
+	mouseTrackingButtonEvent: false,
+	mouseTrackingAnyEvent: false,
+	focusReporting: false,
+	mouseUtf8: false,
+	mouseSgr: false,
+	alternateScreen: false,
+	cursorVisible: true,
+	originMode: false,
+	autoWrap: true,
+};
+
+// =============================================================================
+// Snapshot Types
+// =============================================================================
+
+/**
+ * Snapshot payload returned when attaching to a session.
+ * Contains everything needed to restore terminal state in the renderer.
+ */
+export interface TerminalSnapshot {
+	/** Serialized screen state (ANSI sequences to reproduce screen) */
+	snapshotAnsi: string;
+	/** Control sequences to restore input-affecting modes */
+	rehydrateSequences: string;
+	/** Current working directory (from OSC-7, may be null) */
+	cwd: string | null;
+	/** Current terminal modes */
+	modes: TerminalModes;
+	/** Terminal dimensions */
+	cols: number;
+	rows: number;
+	/** Scrollback line count */
+	scrollbackLines: number;
+	/** Debug diagnostics for troubleshooting (optional) */
+	debug?: {
+		/** xterm's internal buffer type */
+		xtermBufferType: string;
+		/** Whether serialized output contains alt screen entry */
+		hasAltScreenEntry: boolean;
+		/** Alt buffer stats if in alt screen */
+		altBuffer?: {
+			lines: number;
+			nonEmptyLines: number;
+			totalChars: number;
+			cursorX: number;
+			cursorY: number;
+			sampleLines: string[];
+		};
+		/** Normal buffer line count */
+		normalBufferLines: number;
+	};
+}
+
+// =============================================================================
+// Session Types
+// =============================================================================
+
+/**
+ * Session metadata stored on disk
+ */
+export interface SessionMeta {
+	sessionId: string;
+	workspaceId: string;
+	paneId: string;
+	cwd: string;
+	cols: number;
+	rows: number;
+	createdAt: string;
+	lastAttachedAt: string;
+	shell: string;
+}
+
+// =============================================================================
+// IPC Protocol Types
+// =============================================================================
+
+/**
+ * Hello request - initial handshake with daemon
+ */
+export interface HelloRequest {
+	token: string;
+	protocolVersion: number;
+}
+
+export interface HelloResponse {
+	protocolVersion: number;
+	daemonVersion: string;
+	daemonPid: number;
+}
+
+/**
+ * Create or attach to a terminal session
+ */
+export interface CreateOrAttachRequest {
+	sessionId: string;
+	cols: number;
+	rows: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	shell?: string;
+	workspaceId: string;
+	paneId: string;
+	tabId: string;
+	workspaceName?: string;
+	workspacePath?: string;
+	rootPath?: string;
+	initialCommands?: string[];
+}
+
+export interface CreateOrAttachResponse {
+	isNew: boolean;
+	snapshot: TerminalSnapshot;
+	wasRecovered: boolean;
+}
+
+/**
+ * Write data to a terminal session
+ */
+export interface WriteRequest {
+	sessionId: string;
+	data: string;
+}
+
+/**
+ * Resize terminal session
+ */
+export interface ResizeRequest {
+	sessionId: string;
+	cols: number;
+	rows: number;
+}
+
+/**
+ * Detach from a terminal session (keep running)
+ */
+export interface DetachRequest {
+	sessionId: string;
+}
+
+/**
+ * Kill a terminal session
+ */
+export interface KillRequest {
+	sessionId: string;
+	deleteHistory?: boolean;
+}
+
+/**
+ * Kill all terminal sessions
+ */
+export interface KillAllRequest {
+	deleteHistory?: boolean;
+}
+
+/**
+ * List all active sessions
+ */
+export interface ListSessionsResponse {
+	sessions: Array<{
+		sessionId: string;
+		workspaceId: string;
+		paneId: string;
+		isAlive: boolean;
+		attachedClients: number;
+	}>;
+}
+
+/**
+ * Clear scrollback for a session
+ */
+export interface ClearScrollbackRequest {
+	sessionId: string;
+}
+
+/**
+ * Shutdown the daemon gracefully
+ */
+export interface ShutdownRequest {
+	/** Optional: Kill all sessions before shutdown (default: false) */
+	killSessions?: boolean;
+}
+
+// =============================================================================
+// IPC Message Framing
+// =============================================================================
+
+/**
+ * Request message format (client -> daemon)
+ */
+export interface IpcRequest {
+	id: string;
+	type: string;
+	payload: unknown;
+}
+
+/**
+ * Success response format (daemon -> client)
+ */
+export interface IpcSuccessResponse {
+	id: string;
+	ok: true;
+	payload: unknown;
+}
+
+/**
+ * Error response format (daemon -> client)
+ */
+export interface IpcErrorResponse {
+	id: string;
+	ok: false;
+	error: {
+		code: string;
+		message: string;
+	};
+}
+
+export type IpcResponse = IpcSuccessResponse | IpcErrorResponse;
+
+/**
+ * Event message format (daemon -> client, unsolicited)
+ */
+export interface IpcEvent {
+	type: "event";
+	event: string;
+	sessionId: string;
+	payload: unknown;
+}
+
+/**
+ * Terminal data event
+ */
+export interface TerminalDataEvent {
+	type: "data";
+	data: string;
+}
+
+/**
+ * Terminal exit event
+ */
+export interface TerminalExitEvent {
+	type: "exit";
+	exitCode: number;
+	signal?: number;
+}
+
+/**
+ * Terminal error event (e.g., write queue full, subprocess error)
+ */
+export interface TerminalErrorEvent {
+	type: "error";
+	error: string;
+	/** Error code for programmatic handling */
+	code?: "WRITE_QUEUE_FULL" | "SUBPROCESS_ERROR" | "WRITE_FAILED" | "UNKNOWN";
+}
+
+export type TerminalEvent =
+	| TerminalDataEvent
+	| TerminalExitEvent
+	| TerminalErrorEvent;
+
+// =============================================================================
+// Request/Response Type Map
+// =============================================================================
+
+/** Empty response for operations that don't return data */
+export interface EmptyResponse {
+	success: true;
+}
+
+export type RequestTypeMap = {
+	hello: { request: HelloRequest; response: HelloResponse };
+	createOrAttach: {
+		request: CreateOrAttachRequest;
+		response: CreateOrAttachResponse;
+	};
+	write: { request: WriteRequest; response: EmptyResponse };
+	resize: { request: ResizeRequest; response: EmptyResponse };
+	detach: { request: DetachRequest; response: EmptyResponse };
+	kill: { request: KillRequest; response: EmptyResponse };
+	killAll: { request: KillAllRequest; response: EmptyResponse };
+	listSessions: { request: undefined; response: ListSessionsResponse };
+	clearScrollback: { request: ClearScrollbackRequest; response: EmptyResponse };
+	shutdown: { request: ShutdownRequest; response: EmptyResponse };
+};
diff --git a/apps/desktop/src/main/lib/terminal/daemon-manager.ts b/apps/desktop/src/main/lib/terminal/daemon-manager.ts
new file mode 100644
index 00000000000..c67ee3644cf
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal/daemon-manager.ts
@@ -0,0 +1,554 @@
+/**
+ * Daemon-based Terminal Manager
+ *
+ * This version of TerminalManager delegates PTY operations to the
+ * terminal host daemon for persistence across app restarts.
+ *
+ * The daemon owns the PTYs and maintains terminal state. This manager
+ * maintains the same EventEmitter interface as the original for
+ * compatibility with existing TRPC router and renderer code.
+ */
+
+import { EventEmitter } from "node:events";
+import { track } from "main/lib/analytics";
+import {
+	disposeTerminalHostClient,
+	getTerminalHostClient,
+	type TerminalHostClient,
+} from "../terminal-host/client";
+import { buildTerminalEnv, getDefaultShell } from "./env";
+import { portManager } from "./port-manager";
+import type { CreateSessionParams, SessionResult } from "./types";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Delay before removing session from local cache after exit event */
+const SESSION_CLEANUP_DELAY_MS = 5000;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface SessionInfo {
+	paneId: string;
+	workspaceId: string;
+	isAlive: boolean;
+	lastActive: number;
+	cwd: string;
+}
+
+// =============================================================================
+// DaemonTerminalManager
+// =============================================================================
+
+export class DaemonTerminalManager extends EventEmitter {
+	private client: TerminalHostClient;
+	private sessions = new Map<string, SessionInfo>();
+	private pendingSessions = new Map<string, Promise<SessionResult>>();
+
+	constructor() {
+		super();
+		this.client = getTerminalHostClient();
+		this.setupClientEventHandlers();
+	}
+
+	/**
+	 * Set up event handlers to forward daemon events to local EventEmitter
+	 */
+	private setupClientEventHandlers(): void {
+		// Forward data events
+		this.client.on("data", (sessionId: string, data: string) => {
+			// The sessionId from daemon is the paneId
+			const paneId = sessionId;
+
+			// Update session state
+			const session = this.sessions.get(paneId);
+			if (session) {
+				session.lastActive = Date.now();
+			}
+
+			// Scan for port patterns
+			const workspaceId = session?.workspaceId;
+			if (workspaceId) {
+				portManager.scanOutput(data, paneId, workspaceId);
+			}
+
+			// Emit to listeners (TRPC router subscription)
+			this.emit(`data:${paneId}`, data);
+		});
+
+		// Forward exit events
+		this.client.on(
+			"exit",
+			(sessionId: string, exitCode: number, signal?: number) => {
+				const paneId = sessionId;
+
+				// Update session state
+				const session = this.sessions.get(paneId);
+				if (session) {
+					session.isAlive = false;
+				}
+
+				// Clean up detected ports
+				portManager.removePortsForPane(paneId);
+
+				// Emit exit event
+				this.emit(`exit:${paneId}`, exitCode, signal);
+
+				// Clean up session after delay
+				setTimeout(() => {
+					this.sessions.delete(paneId);
+				}, SESSION_CLEANUP_DELAY_MS);
+			},
+		);
+
+		// Handle client disconnection - notify all active sessions
+		this.client.on("disconnected", () => {
+			console.warn("[DaemonTerminalManager] Disconnected from daemon");
+			// Emit disconnect event for all active sessions so terminals can show error UI
+			for (const [paneId, session] of this.sessions.entries()) {
+				if (session.isAlive) {
+					this.emit(
+						`disconnect:${paneId}`,
+						"Connection to terminal daemon lost",
+					);
+				}
+			}
+		});
+
+		this.client.on("error", (error: Error) => {
+			console.error("[DaemonTerminalManager] Client error:", error.message);
+			// Emit error event for all active sessions
+			for (const [paneId, session] of this.sessions.entries()) {
+				if (session.isAlive) {
+					this.emit(`disconnect:${paneId}`, error.message);
+				}
+			}
+		});
+
+		// Terminal-specific errors (e.g., subprocess backpressure limits)
+		this.client.on(
+			"terminalError",
+			(sessionId: string, error: string, code?: string) => {
+				const paneId = sessionId;
+				console.error(
+					`[DaemonTerminalManager] Terminal error for ${paneId}: ${code ?? "UNKNOWN"}: ${error}`,
+				);
+				this.emit(`error:${paneId}`, { error, code });
+			},
+		);
+	}
+
+	// ===========================================================================
+	// Public API (matches original TerminalManager interface)
+	// ===========================================================================
+
+	async createOrAttach(params: CreateSessionParams): Promise<SessionResult> {
+		const { paneId } = params;
+
+		// Deduplicate concurrent calls
+		const pending = this.pendingSessions.get(paneId);
+		if (pending) {
+			return pending;
+		}
+
+		const creationPromise = this.doCreateOrAttach(params);
+		this.pendingSessions.set(paneId, creationPromise);
+
+		try {
+			return await creationPromise;
+		} finally {
+			this.pendingSessions.delete(paneId);
+		}
+	}
+
+	private async doCreateOrAttach(
+		params: CreateSessionParams,
+	): Promise<SessionResult> {
+		const {
+			paneId,
+			tabId,
+			workspaceId,
+			workspaceName,
+			workspacePath,
+			rootPath,
+			cwd,
+			cols = 80,
+			rows = 24,
+			initialCommands,
+		} = params;
+
+		console.log(
+			`[DaemonTerminalManager] createOrAttach called for paneId: ${paneId}`,
+		);
+
+		// Build environment for the terminal
+		const shell = getDefaultShell();
+		const env = buildTerminalEnv({
+			shell,
+			paneId,
+			tabId,
+			workspaceId,
+			workspaceName,
+			workspacePath,
+			rootPath,
+		});
+
+		// Call daemon
+		console.log(
+			`[DaemonTerminalManager] Calling daemon createOrAttach with sessionId: ${paneId}`,
+		);
+		const response = await this.client.createOrAttach({
+			sessionId: paneId, // Use paneId as sessionId for simplicity
+			paneId,
+			tabId,
+			workspaceId,
+			workspaceName,
+			workspacePath,
+			rootPath,
+			cols,
+			rows,
+			cwd,
+			env,
+			shell,
+			initialCommands,
+		});
+
+		console.log(
+			`[DaemonTerminalManager] Daemon response: isNew=${response.isNew}, wasRecovered=${response.wasRecovered}`,
+		);
+
+		// Track session locally
+		this.sessions.set(paneId, {
+			paneId,
+			workspaceId,
+			isAlive: true,
+			lastActive: Date.now(),
+			cwd: response.snapshot.cwd || cwd || "",
+		});
+
+		// Track terminal opened
+		if (response.isNew) {
+			track("terminal_opened", { workspace_id: workspaceId, pane_id: paneId });
+		}
+
+		return {
+			isNew: response.isNew,
+			// In daemon mode, snapshot.snapshotAnsi is the canonical content source.
+			// We set scrollback to empty to avoid duplicating the payload over IPC.
+			// The renderer should prefer snapshot.snapshotAnsi when available.
+			scrollback: "",
+			wasRecovered: response.wasRecovered,
+			snapshot: {
+				snapshotAnsi: response.snapshot.snapshotAnsi,
+				rehydrateSequences: response.snapshot.rehydrateSequences,
+				cwd: response.snapshot.cwd,
+				modes: response.snapshot.modes as unknown as Record<string, boolean>,
+				cols: response.snapshot.cols,
+				rows: response.snapshot.rows,
+				scrollbackLines: response.snapshot.scrollbackLines,
+				debug: response.snapshot.debug,
+			},
+		};
+	}
+
+	write(params: { paneId: string; data: string }): void {
+		const { paneId, data } = params;
+
+		const session = this.sessions.get(paneId);
+		if (!session || !session.isAlive) {
+			throw new Error(`Terminal session ${paneId} not found or not alive`);
+		}
+
+		// Fire and forget - daemon will handle the write.
+		// Use the no-ack fast path to avoid per-chunk request timeouts under load.
+		this.client.writeNoAck({ sessionId: paneId, data });
+
+		session.lastActive = Date.now();
+	}
+
+	resize(params: { paneId: string; cols: number; rows: number }): void {
+		const { paneId, cols, rows } = params;
+
+		// Validate geometry
+		if (
+			!Number.isInteger(cols) ||
+			!Number.isInteger(rows) ||
+			cols <= 0 ||
+			rows <= 0
+		) {
+			console.warn(
+				`[DaemonTerminalManager] Invalid resize geometry for ${paneId}: cols=${cols}, rows=${rows}`,
+			);
+			return;
+		}
+
+		const session = this.sessions.get(paneId);
+		if (!session || !session.isAlive) {
+			console.warn(
+				`Cannot resize terminal ${paneId}: session not found or not alive`,
+			);
+			return;
+		}
+
+		// Fire and forget
+		this.client.resize({ sessionId: paneId, cols, rows }).catch((error) => {
+			console.error(
+				`[DaemonTerminalManager] Resize failed for ${paneId}:`,
+				error,
+			);
+		});
+
+		session.lastActive = Date.now();
+	}
+
+	signal(params: { paneId: string; signal?: string }): void {
+		const { paneId, signal = "SIGTERM" } = params;
+		const session = this.sessions.get(paneId);
+
+		if (!session || !session.isAlive) {
+			console.warn(
+				`Cannot signal terminal ${paneId}: session not found or not alive`,
+			);
+			return;
+		}
+
+		// Daemon doesn't have a signal method, use kill
+		// For now, just log - we may need to add signal support to daemon
+		console.warn(
+			`[DaemonTerminalManager] Signal ${signal} not yet supported for daemon sessions`,
+		);
+	}
+
+	async kill(params: {
+		paneId: string;
+		deleteHistory?: boolean;
+	}): Promise<void> {
+		const { paneId, deleteHistory = false } = params;
+
+		// Emit exit event BEFORE killing so tRPC subscriptions complete cleanly.
+		// This prevents WRITE_FAILED errors when the daemon kills the session
+		// but React components are still mounted with active subscriptions.
+		// The daemon will also emit an exit event, but duplicate events are
+		// harmless since emit.complete() has already been called.
+		const session = this.sessions.get(paneId);
+		if (session?.isAlive) {
+			session.isAlive = false;
+			this.emit(`exit:${paneId}`, 0, "SIGTERM");
+		}
+
+		await this.client.kill({ sessionId: paneId, deleteHistory });
+	}
+
+	detach(params: { paneId: string }): void {
+		const { paneId } = params;
+
+		const session = this.sessions.get(paneId);
+		if (!session) {
+			console.warn(`Cannot detach terminal ${paneId}: session not found`);
+			return;
+		}
+
+		// Fire and forget
+		this.client.detach({ sessionId: paneId }).catch((error) => {
+			console.error(
+				`[DaemonTerminalManager] Detach failed for ${paneId}:`,
+				error,
+			);
+		});
+
+		session.lastActive = Date.now();
+	}
+
+	async clearScrollback(params: { paneId: string }): Promise<void> {
+		const { paneId } = params;
+
+		await this.client.clearScrollback({ sessionId: paneId });
+
+		const session = this.sessions.get(paneId);
+		if (session) {
+			session.lastActive = Date.now();
+		}
+	}
+
+	getSession(
+		paneId: string,
+	): { isAlive: boolean; cwd: string; lastActive: number } | null {
+		const session = this.sessions.get(paneId);
+		if (!session) {
+			return null;
+		}
+
+		return {
+			isAlive: session.isAlive,
+			cwd: session.cwd,
+			lastActive: session.lastActive,
+		};
+	}
+
+	async killByWorkspaceId(
+		workspaceId: string,
+	): Promise<{ killed: number; failed: number }> {
+		// Always query daemon for the authoritative list of sessions
+		// Local sessions map may be incomplete after app restart
+		const paneIdsToKill = new Set<string>();
+
+		// Query daemon for all sessions in this workspace
+		try {
+			const response = await this.client.listSessions();
+			for (const session of response.sessions) {
+				if (session.workspaceId === workspaceId && session.isAlive) {
+					paneIdsToKill.add(session.paneId);
+				}
+			}
+		} catch (error) {
+			console.warn(
+				"[DaemonTerminalManager] Failed to query daemon for sessions:",
+				error,
+			);
+			// Fall back to local sessions if daemon query fails
+			for (const [paneId, session] of this.sessions.entries()) {
+				if (session.workspaceId === workspaceId) {
+					paneIdsToKill.add(paneId);
+				}
+			}
+		}
+
+		if (paneIdsToKill.size === 0) {
+			return { killed: 0, failed: 0 };
+		}
+
+		console.log(
+			`[DaemonTerminalManager] Killing ${paneIdsToKill.size} sessions for workspace ${workspaceId}`,
+		);
+
+		let killed = 0;
+		let failed = 0;
+
+		for (const paneId of paneIdsToKill) {
+			try {
+				// Emit exit event BEFORE killing so tRPC subscriptions complete cleanly.
+				// This prevents WRITE_FAILED error toast floods when deleting workspaces.
+				const session = this.sessions.get(paneId);
+				if (session?.isAlive) {
+					session.isAlive = false;
+					this.emit(`exit:${paneId}`, 0, "SIGTERM");
+				}
+
+				await this.client.kill({ sessionId: paneId, deleteHistory: true });
+				killed++;
+			} catch (error) {
+				console.error(
+					`[DaemonTerminalManager] Failed to kill session ${paneId}:`,
+					error,
+				);
+				failed++;
+			}
+		}
+
+		if (failed > 0) {
+			console.warn(
+				`[DaemonTerminalManager] killByWorkspaceId: killed=${killed}, failed=${failed}`,
+			);
+		}
+
+		return { killed, failed };
+	}
+
+	async getSessionCountByWorkspaceId(workspaceId: string): Promise<number> {
+		// Always query daemon for the authoritative count
+		// Local sessions map may be incomplete after app restart
+		try {
+			const response = await this.client.listSessions();
+			return response.sessions.filter(
+				(s) => s.workspaceId === workspaceId && s.isAlive,
+			).length;
+		} catch (error) {
+			console.warn(
+				"[DaemonTerminalManager] Failed to query daemon for session count:",
+				error,
+			);
+			// Fall back to local sessions if daemon query fails
+			return Array.from(this.sessions.values()).filter(
+				(session) => session.workspaceId === workspaceId && session.isAlive,
+			).length;
+		}
+	}
+
+	/**
+	 * Send a newline to all terminals in a workspace to refresh their prompts.
+	 */
+	refreshPromptsForWorkspace(workspaceId: string): void {
+		for (const [paneId, session] of this.sessions.entries()) {
+			if (session.workspaceId === workspaceId && session.isAlive) {
+				this.client.writeNoAck({ sessionId: paneId, data: "\n" });
+			}
+		}
+	}
+
+	detachAllListeners(): void {
+		for (const event of this.eventNames()) {
+			const name = String(event);
+			if (
+				name.startsWith("data:") ||
+				name.startsWith("exit:") ||
+				name.startsWith("disconnect:") ||
+				name.startsWith("error:")
+			) {
+				this.removeAllListeners(event);
+			}
+		}
+	}
+
+	/**
+	 * Cleanup on app quit.
+	 *
+	 * IMPORTANT: In daemon mode, we intentionally do NOT kill sessions.
+	 * The whole point of the daemon is to persist terminals across app restarts.
+	 * We only disconnect from the daemon and clear local state.
+	 */
+	async cleanup(): Promise<void> {
+		// Disconnect from daemon but DON'T kill sessions - they should persist
+		// across app restarts. This is the core feature of daemon mode.
+		this.sessions.clear();
+		this.removeAllListeners();
+		disposeTerminalHostClient();
+	}
+
+	/**
+	 * Forcefully kill all sessions in the daemon.
+	 * Only use this when you explicitly want to destroy all terminals,
+	 * not during normal app shutdown.
+	 */
+	async forceKillAll(): Promise<void> {
+		await this.client.killAll({});
+		this.sessions.clear();
+	}
+}
+
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+
+let daemonManager: DaemonTerminalManager | null = null;
+
+export function getDaemonTerminalManager(): DaemonTerminalManager {
+	if (!daemonManager) {
+		daemonManager = new DaemonTerminalManager();
+	}
+	return daemonManager;
+}
+
+/**
+ * Dispose the daemon manager singleton.
+ * Must be called when the terminal host client is disposed (e.g., daemon restart)
+ * to ensure the manager gets a fresh client reference on next use.
+ */
+export function disposeDaemonManager(): void {
+	if (daemonManager) {
+		daemonManager.removeAllListeners();
+		daemonManager = null;
+	}
+}
diff --git a/apps/desktop/src/main/lib/terminal/env.test.ts b/apps/desktop/src/main/lib/terminal/env.test.ts
index f8fb5b1e5fd..57946088e55 100644
--- a/apps/desktop/src/main/lib/terminal/env.test.ts
+++ b/apps/desktop/src/main/lib/terminal/env.test.ts
@@ -177,5 +177,17 @@ describe("env", () => {
 			expect(result.SUPERSET_PORT).toBeDefined();
 			expect(typeof result.SUPERSET_PORT).toBe("string");
 		});
+
+		it("should include SUPERSET_ENV for dev/prod separation", () => {
+			const result = buildTerminalEnv(baseParams);
+			expect(result.SUPERSET_ENV).toBeDefined();
+			expect(["development", "production"]).toContain(result.SUPERSET_ENV);
+		});
+
+		it("should include SUPERSET_HOOK_VERSION for protocol versioning", () => {
+			const result = buildTerminalEnv(baseParams);
+			expect(result.SUPERSET_HOOK_VERSION).toBeDefined();
+			expect(result.SUPERSET_HOOK_VERSION).toBe("2");
+		});
 	});
 });
diff --git a/apps/desktop/src/main/lib/terminal/env.ts b/apps/desktop/src/main/lib/terminal/env.ts
index d5931a908f1..d491f215d91 100644
--- a/apps/desktop/src/main/lib/terminal/env.ts
+++ b/apps/desktop/src/main/lib/terminal/env.ts
@@ -2,8 +2,16 @@ import { execSync } from "node:child_process";
 import os from "node:os";
 import defaultShell from "default-shell";
 import { PORTS } from "shared/constants";
+import { env } from "shared/env.shared";
 import { getShellEnv } from "../agent-setup/shell-wrappers";
 
+/**
+ * Current hook protocol version.
+ * Increment when making breaking changes to the hook protocol.
+ * The server logs this for debugging version mismatches.
+ */
+export const HOOK_PROTOCOL_VERSION = "2";
+
 export const FALLBACK_SHELL = os.platform() === "win32" ? "cmd.exe" : "/bin/sh";
 export const SHELL_CRASH_THRESHOLD_MS = 1000;
 
@@ -86,7 +94,7 @@ export function buildTerminalEnv(params: {
 	const shellEnv = getShellEnv(shell);
 	const locale = getLocale(baseEnv);
 
-	const env: Record<string, string> = {
+	const terminalEnv: Record<string, string> = {
 		...baseEnv,
 		...shellEnv,
 		TERM_PROGRAM: "Superset",
@@ -100,9 +108,13 @@ export function buildTerminalEnv(params: {
 		SUPERSET_WORKSPACE_PATH: workspacePath || "",
 		SUPERSET_ROOT_PATH: rootPath || "",
 		SUPERSET_PORT: String(PORTS.NOTIFICATIONS),
+		// Environment identifier for dev/prod separation
+		SUPERSET_ENV: env.NODE_ENV === "development" ? "development" : "production",
+		// Hook protocol version for forward compatibility
+		SUPERSET_HOOK_VERSION: HOOK_PROTOCOL_VERSION,
 	};
 
-	delete env.GOOGLE_API_KEY;
+	delete terminalEnv.GOOGLE_API_KEY;
 
-	return env;
+	return terminalEnv;
 }
diff --git a/apps/desktop/src/main/lib/terminal/index.ts b/apps/desktop/src/main/lib/terminal/index.ts
index 190aa9dd342..ef80cfb8e00 100644
--- a/apps/desktop/src/main/lib/terminal/index.ts
+++ b/apps/desktop/src/main/lib/terminal/index.ts
@@ -1,4 +1,17 @@
-export { TerminalManager, terminalManager } from "./manager";
+import { settings } from "@superset/local-db";
+import { localDb } from "main/lib/local-db";
+import {
+	disposeTerminalHostClient,
+	getTerminalHostClient,
+} from "main/lib/terminal-host/client";
+import {
+	DaemonTerminalManager,
+	getDaemonTerminalManager,
+} from "./daemon-manager";
+import { TerminalManager, terminalManager } from "./manager";
+
+export { TerminalManager, terminalManager };
+export { DaemonTerminalManager, getDaemonTerminalManager };
 export type {
 	CreateSessionParams,
 	SessionResult,
@@ -6,3 +19,99 @@ export type {
 	TerminalEvent,
 	TerminalExitEvent,
 } from "./types";
+
+// =============================================================================
+// Terminal Manager Selection
+// =============================================================================
+
+// Cache the daemon mode setting to avoid repeated DB reads
+// This is set once at app startup and doesn't change until restart
+let cachedDaemonMode: boolean | null = null;
+
+/**
+ * Check if daemon mode is enabled.
+ * Reads from user settings (terminalPersistence) or falls back to env var.
+ * The value is cached since it requires app restart to take effect.
+ */
+export function isDaemonModeEnabled(): boolean {
+	// Return cached value if available
+	if (cachedDaemonMode !== null) {
+		return cachedDaemonMode;
+	}
+
+	// First check environment variable override (for development/testing)
+	if (process.env.SUPERSET_TERMINAL_DAEMON === "1") {
+		console.log(
+			"[TerminalManager] Daemon mode: ENABLED (via SUPERSET_TERMINAL_DAEMON env var)",
+		);
+		cachedDaemonMode = true;
+		return true;
+	}
+
+	// Read from user settings
+	try {
+		const row = localDb.select().from(settings).get();
+		const enabled = row?.terminalPersistence ?? false;
+		console.log(
+			`[TerminalManager] Daemon mode: ${enabled ? "ENABLED" : "DISABLED"} (via settings.terminalPersistence)`,
+		);
+		cachedDaemonMode = enabled;
+		return enabled;
+	} catch (error) {
+		console.warn(
+			"[TerminalManager] Failed to read settings, defaulting to disabled:",
+			error,
+		);
+		cachedDaemonMode = false;
+		return false;
+	}
+}
+
+/**
+ * Get the active terminal manager based on current settings.
+ * Returns either the in-process manager or the daemon-based manager.
+ */
+export function getActiveTerminalManager():
+	| TerminalManager
+	| DaemonTerminalManager {
+	if (isDaemonModeEnabled()) {
+		return getDaemonTerminalManager();
+	}
+	return terminalManager;
+}
+
+/**
+ * Shutdown any orphaned daemon process.
+ * Should be called on app startup when daemon mode is disabled to clean up
+ * any daemon left running from a previous session with persistence enabled.
+ *
+ * Uses shutdownIfRunning() to avoid spawning a new daemon just to shut it down.
+ */
+export async function shutdownOrphanedDaemon(): Promise<void> {
+	if (isDaemonModeEnabled()) {
+		// Daemon mode is enabled, don't shutdown
+		return;
+	}
+
+	try {
+		const client = getTerminalHostClient();
+		// Use shutdownIfRunning to avoid spawning a daemon if none exists
+		const { wasRunning } = await client.shutdownIfRunning({
+			killSessions: true,
+		});
+		if (wasRunning) {
+			console.log("[TerminalManager] Shutdown orphaned daemon successfully");
+		} else {
+			console.log("[TerminalManager] No orphaned daemon to shutdown");
+		}
+	} catch (error) {
+		// Unexpected error during shutdown attempt
+		console.warn(
+			"[TerminalManager] Error during orphan daemon cleanup:",
+			error,
+		);
+	} finally {
+		// Always dispose the client to clean up any partial state
+		disposeTerminalHostClient();
+	}
+}
diff --git a/apps/desktop/src/main/lib/terminal/manager.test.ts b/apps/desktop/src/main/lib/terminal/manager.test.ts
index e49cb8bfca5..87fd7767168 100644
--- a/apps/desktop/src/main/lib/terminal/manager.test.ts
+++ b/apps/desktop/src/main/lib/terminal/manager.test.ts
@@ -165,6 +165,9 @@ describe("TerminalManager", () => {
 				data: "ls -la\n",
 			});
 
+			// Wait for PtyWriteQueue async flush (uses setTimeout internally)
+			await new Promise((resolve) => setTimeout(resolve, 20));
+
 			expect(mockPty.write).toHaveBeenCalledWith("ls -la\n");
 		});
 
@@ -664,12 +667,18 @@ describe("TerminalManager", () => {
 				workspaceId: "other-workspace",
 			});
 
-			expect(manager.getSessionCountByWorkspaceId("workspace-count")).toBe(2);
-			expect(manager.getSessionCountByWorkspaceId("other-workspace")).toBe(1);
+			expect(
+				await manager.getSessionCountByWorkspaceId("workspace-count"),
+			).toBe(2);
+			expect(
+				await manager.getSessionCountByWorkspaceId("other-workspace"),
+			).toBe(1);
 		});
 
-		it("should return zero for non-existent workspace", () => {
-			expect(manager.getSessionCountByWorkspaceId("non-existent")).toBe(0);
+		it("should return zero for non-existent workspace", async () => {
+			expect(await manager.getSessionCountByWorkspaceId("non-existent")).toBe(
+				0,
+			);
 		});
 
 		it("should not count dead sessions", async () => {
@@ -695,7 +704,9 @@ describe("TerminalManager", () => {
 			// Wait for state to update
 			await new Promise((resolve) => setTimeout(resolve, 100));
 
-			expect(manager.getSessionCountByWorkspaceId("workspace-mixed")).toBe(1);
+			expect(
+				await manager.getSessionCountByWorkspaceId("workspace-mixed"),
+			).toBe(1);
 		});
 	});
 
diff --git a/apps/desktop/src/main/lib/terminal/manager.ts b/apps/desktop/src/main/lib/terminal/manager.ts
index 4541b75d664..e85096293ca 100644
--- a/apps/desktop/src/main/lib/terminal/manager.ts
+++ b/apps/desktop/src/main/lib/terminal/manager.ts
@@ -110,6 +110,7 @@ export class TerminalManager extends EventEmitter {
 
 		session.pty.onExit(async ({ exitCode, signal }) => {
 			session.isAlive = false;
+			session.writeQueue.dispose();
 			flushSession(session);
 
 			// Check if shell crashed quickly - try fallback
@@ -163,7 +164,9 @@ export class TerminalManager extends EventEmitter {
 			throw new Error(`Terminal session ${paneId} not found or not alive`);
 		}
 
-		session.pty.write(data);
+		if (!session.writeQueue.write(data)) {
+			throw new Error(`Terminal ${paneId} write queue full`);
+		}
 		session.lastActive = Date.now();
 	}
 
@@ -314,12 +317,14 @@ export class TerminalManager extends EventEmitter {
 	): Promise<boolean> {
 		if (!session.isAlive) {
 			session.deleteHistoryOnExit = true;
+			session.writeQueue.dispose();
 			await closeSessionHistory(session);
 			this.sessions.delete(paneId);
 			return true;
 		}
 
 		session.deleteHistoryOnExit = true;
+		session.writeQueue.dispose();
 
 		return new Promise<boolean>((resolve) => {
 			let resolved = false;
@@ -378,7 +383,7 @@ export class TerminalManager extends EventEmitter {
 		});
 	}
 
-	getSessionCountByWorkspaceId(workspaceId: string): number {
+	async getSessionCountByWorkspaceId(workspaceId: string): Promise<number> {
 		return Array.from(this.sessions.values()).filter(
 			(session) => session.workspaceId === workspaceId && session.isAlive,
 		).length;
@@ -392,7 +397,7 @@ export class TerminalManager extends EventEmitter {
 		for (const [paneId, session] of this.sessions.entries()) {
 			if (session.workspaceId === workspaceId && session.isAlive) {
 				try {
-					session.pty.write("\n");
+					session.writeQueue.write("\n");
 				} catch (error) {
 					console.warn(
 						`[TerminalManager] Failed to refresh prompt for pane ${paneId}:`,
@@ -406,7 +411,12 @@ export class TerminalManager extends EventEmitter {
 	detachAllListeners(): void {
 		for (const event of this.eventNames()) {
 			const name = String(event);
-			if (name.startsWith("data:") || name.startsWith("exit:")) {
+			if (
+				name.startsWith("data:") ||
+				name.startsWith("exit:") ||
+				name.startsWith("disconnect:") ||
+				name.startsWith("error:")
+			) {
 				this.removeAllListeners(event);
 			}
 		}
@@ -436,8 +446,10 @@ export class TerminalManager extends EventEmitter {
 				});
 
 				exitPromises.push(exitPromise);
+				session.writeQueue.dispose();
 				session.pty.kill();
 			} else {
+				session.writeQueue.dispose();
 				await closeSessionHistory(session);
 			}
 		}
diff --git a/apps/desktop/src/main/lib/terminal/port-manager.ts b/apps/desktop/src/main/lib/terminal/port-manager.ts
index b848024fc85..5d8995ffa1d 100644
--- a/apps/desktop/src/main/lib/terminal/port-manager.ts
+++ b/apps/desktop/src/main/lib/terminal/port-manager.ts
@@ -328,13 +328,25 @@ class PortManager extends EventEmitter {
 		const buffered = this.lineBuffers.get(paneId) || "";
 		const combined = buffered + data;
 
-		// Split by newlines
-		const parts = combined.split(/\r?\n/);
+		// Fast path: avoid splitting/regex on obviously irrelevant output (e.g., full-screen TUIs).
+		// Still maintain the incomplete-line buffer so patterns spanning chunks can be detected later.
+		const lastNewlineIndex = Math.max(
+			combined.lastIndexOf("\n"),
+			combined.lastIndexOf("\r"),
+		);
+
+		// No newline yet → only an incomplete line to buffer.
+		if (lastNewlineIndex === -1) {
+			if (combined.length <= MAX_LINE_BUFFER) {
+				this.lineBuffers.set(paneId, combined);
+			} else {
+				this.lineBuffers.delete(paneId);
+			}
+			return;
+		}
 
-		// If data doesn't end with a newline, the last part is incomplete - buffer it
-		const endsWithNewline = /[\r\n]$/.test(data);
-		const completeLines = endsWithNewline ? parts : parts.slice(0, -1);
-		const incompleteLine = endsWithNewline ? "" : (parts.at(-1) ?? "");
+		const completePart = combined.slice(0, lastNewlineIndex);
+		const incompleteLine = combined.slice(lastNewlineIndex + 1);
 
 		// Update buffer (with size limit to prevent memory issues)
 		if (incompleteLine && incompleteLine.length <= MAX_LINE_BUFFER) {
@@ -343,13 +355,26 @@ class PortManager extends EventEmitter {
 			this.lineBuffers.delete(paneId);
 		}
 
-		// Process complete lines
+		// Heuristic: only do full line processing if the chunk *looks* like it could contain a port.
+		// Sample both the head and tail to handle long logs without scanning huge strings.
+		const sample =
+			completePart.length > 4096
+				? `${completePart.slice(0, 2048)}${completePart.slice(-2048)}`
+				: completePart;
+		const looksRelevant =
+			/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|https?:\/\/|listening|started|ready|running|\bon port\b)/i.test(
+				sample,
+			);
+		if (!looksRelevant) return;
+
+		// Split by newlines (only on the completed portion)
+		const completeLines = completePart.split(/\r?\n/);
+
 		for (const line of completeLines) {
 			if (!line.trim()) continue;
 
 			const port = extractPort(line);
 			if (port !== null) {
-				// Schedule verification - port will only be added if it's actually listening
 				this.schedulePortVerification(port, paneId, workspaceId, line);
 			}
 		}
diff --git a/apps/desktop/src/main/lib/terminal/pty-write-queue.ts b/apps/desktop/src/main/lib/terminal/pty-write-queue.ts
new file mode 100644
index 00000000000..e0e4131bb15
--- /dev/null
+++ b/apps/desktop/src/main/lib/terminal/pty-write-queue.ts
@@ -0,0 +1,159 @@
+import type { IPty } from "node-pty";
+
+/**
+ * A write queue for PTY that reduces event loop starvation.
+ *
+ * Context: This is used in the non-daemon (in-process) terminal mode.
+ * For daemon mode, the real backpressure handling (EAGAIN retry with backoff)
+ * is implemented in pty-subprocess.ts.
+ *
+ * Problem: node-pty's write() is synchronous. While the kernel buffer rarely
+ * fills completely, processing large pastes in a single event loop tick can
+ * starve other work (IPC handlers, UI updates).
+ *
+ * Solution: Queue writes and process them in small chunks, yielding to the
+ * event loop between chunks via setTimeout. This improves responsiveness
+ * during large pastes.
+ *
+ * Limitations:
+ * - Does NOT handle true kernel-level backpressure (EAGAIN/EWOULDBLOCK)
+ * - If node-pty.write() blocks, this cannot prevent it
+ * - For robust backpressure handling, use daemon mode with subprocess isolation
+ *
+ * Features:
+ * - Chunked writes to reduce event loop starvation
+ * - Memory-bounded queue to prevent OOM
+ * - Backpressure signaling when queue is full
+ * - Graceful handling of PTY closure
+ */
+export class PtyWriteQueue {
+	private queue: string[] = [];
+	private queuedBytes = 0;
+	private flushing = false;
+	private disposed = false;
+
+	/**
+	 * Size of each write chunk. Smaller = more responsive but slower throughput.
+	 * 256 bytes keeps individual blocks short (~1-5ms typically).
+	 */
+	private readonly CHUNK_SIZE = 256;
+
+	/**
+	 * Delay between chunks in ms. Gives event loop time to process other work.
+	 */
+	private readonly CHUNK_DELAY_MS = 1;
+
+	/**
+	 * Maximum bytes allowed in queue. Prevents OOM if PTY stops consuming.
+	 * 1MB is generous - a typical large paste is ~50KB.
+	 */
+	private readonly MAX_QUEUE_BYTES = 1_000_000;
+
+	constructor(
+		private pty: IPty,
+		private onDrain?: () => void,
+	) {}
+
+	/**
+	 * Queue data to be written to the PTY.
+	 * @returns true if queued, false if queue is full (backpressure)
+	 */
+	write(data: string): boolean {
+		if (this.disposed) {
+			return false;
+		}
+
+		if (this.queuedBytes + data.length > this.MAX_QUEUE_BYTES) {
+			console.warn(
+				`[PtyWriteQueue] Queue full (${this.queuedBytes} bytes), rejecting write of ${data.length} bytes`,
+			);
+			return false;
+		}
+
+		this.queue.push(data);
+		this.queuedBytes += data.length;
+		this.scheduleFlush();
+		return true;
+	}
+
+	/**
+	 * Schedule the flush loop if not already running.
+	 */
+	private scheduleFlush(): void {
+		if (this.flushing || this.disposed) return;
+		this.flushing = true;
+		setTimeout(() => this.flush(), 0);
+	}
+
+	/**
+	 * Process one chunk from the queue and schedule the next.
+	 */
+	private flush(): void {
+		if (this.disposed) {
+			this.flushing = false;
+			return;
+		}
+
+		if (this.queue.length === 0) {
+			this.flushing = false;
+			this.onDrain?.();
+			return;
+		}
+
+		// Take a chunk from front of queue
+		let chunk = this.queue[0];
+		if (chunk.length > this.CHUNK_SIZE) {
+			// Split: take CHUNK_SIZE, leave rest in queue
+			this.queue[0] = chunk.slice(this.CHUNK_SIZE);
+			chunk = chunk.slice(0, this.CHUNK_SIZE);
+		} else {
+			// Take entire item
+			this.queue.shift();
+		}
+
+		this.queuedBytes -= chunk.length;
+
+		try {
+			this.pty.write(chunk);
+		} catch (error) {
+			// PTY might be closed - clear queue and stop
+			console.warn("[PtyWriteQueue] Write failed, clearing queue:", error);
+			this.clear();
+			this.flushing = false;
+			return;
+		}
+
+		// Yield to event loop with a small delay, allowing other work to run
+		setTimeout(() => this.flush(), this.CHUNK_DELAY_MS);
+	}
+
+	/**
+	 * Number of bytes currently queued.
+	 */
+	get pending(): number {
+		return this.queuedBytes;
+	}
+
+	/**
+	 * Whether there's data waiting to be written.
+	 */
+	get hasPending(): boolean {
+		return this.queuedBytes > 0;
+	}
+
+	/**
+	 * Clear all pending writes.
+	 */
+	clear(): void {
+		this.queue = [];
+		this.queuedBytes = 0;
+	}
+
+	/**
+	 * Stop processing and clear queue.
+	 */
+	dispose(): void {
+		this.disposed = true;
+		this.clear();
+	}
+}
diff --git a/apps/desktop/src/main/lib/terminal/session.ts b/apps/desktop/src/main/lib/terminal/session.ts
index 08b5c559f00..e8ba5d04a1d 100644
--- a/apps/desktop/src/main/lib/terminal/session.ts
+++ b/apps/desktop/src/main/lib/terminal/session.ts
@@ -9,6 +9,7 @@ import {
 import { HistoryReader, HistoryWriter } from "../terminal-history";
 import { buildTerminalEnv, FALLBACK_SHELL, getDefaultShell } from "./env";
 import { portManager } from "./port-manager";
+import { PtyWriteQueue } from "./pty-write-queue";
 import type { InternalCreateSessionParams, TerminalSession } from "./types";
 
 const DEFAULT_COLS = 80;
@@ -122,6 +123,8 @@ export async function createSession(
 		onData(paneId, batchedData);
 	});
 
+	const writeQueue = new PtyWriteQueue(ptyProcess);
+
 	return {
 		pty: ptyProcess,
 		paneId,
@@ -135,6 +138,7 @@ export async function createSession(
 		wasRecovered,
 		historyWriter,
 		dataBatcher,
+		writeQueue,
 		shell,
 		startTime: Date.now(),
 		usedFallback: useFallbackShell,
@@ -186,7 +190,7 @@ export function setupDataHandler(
 						}
 
 						if (session.isAlive) {
-							session.pty.write(initialCommandString);
+							session.writeQueue.write(initialCommandString);
 						}
 					})();
 				}
diff --git a/apps/desktop/src/main/lib/terminal/types.ts b/apps/desktop/src/main/lib/terminal/types.ts
index 0a53eb35a78..eebd65bc949 100644
--- a/apps/desktop/src/main/lib/terminal/types.ts
+++ b/apps/desktop/src/main/lib/terminal/types.ts
@@ -1,6 +1,7 @@
 import type * as pty from "node-pty";
 import type { DataBatcher } from "../data-batcher";
 import type { HistoryWriter } from "../terminal-history";
+import type { PtyWriteQueue } from "./pty-write-queue";
 
 export interface TerminalSession {
 	pty: pty.IPty;
@@ -16,6 +17,8 @@ export interface TerminalSession {
 	wasRecovered: boolean;
 	historyWriter?: HistoryWriter;
 	dataBatcher: DataBatcher;
+	/** Queued writer to prevent blocking on large writes */
+	writeQueue: PtyWriteQueue;
 	shell: string;
 	startTime: number;
 	usedFallback: boolean;
@@ -36,8 +39,37 @@ export type TerminalEvent = TerminalDataEvent | TerminalExitEvent;
 
 export interface SessionResult {
 	isNew: boolean;
+	/**
+	 * Initial terminal content (ANSI).
+	 * In daemon mode, this is empty - prefer `snapshot.snapshotAnsi` when available.
+	 * In non-daemon mode, this contains the recovered scrollback content.
+	 */
 	scrollback: string;
 	wasRecovered: boolean;
+	/** Snapshot from daemon (if using daemon mode) */
+	snapshot?: {
+		snapshotAnsi: string;
+		rehydrateSequences: string;
+		cwd: string | null;
+		modes: Record<string, boolean>;
+		cols: number;
+		rows: number;
+		scrollbackLines: number;
+		/** Debug diagnostics for troubleshooting */
+		debug?: {
+			xtermBufferType: string;
+			hasAltScreenEntry: boolean;
+			altBuffer?: {
+				lines: number;
+				nonEmptyLines: number;
+				totalChars: number;
+				cursorX: number;
+				cursorY: number;
+				sampleLines: string[];
+			};
+			normalBufferLines: number;
+		};
+	};
 }
 
 export interface CreateSessionParams {
diff --git a/apps/desktop/src/main/terminal-host/daemon.test.ts b/apps/desktop/src/main/terminal-host/daemon.test.ts
new file mode 100644
index 00000000000..69049f10d50
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/daemon.test.ts
@@ -0,0 +1,429 @@
+/**
+ * Terminal Host Daemon Integration Tests
+ *
+ * These tests verify the daemon can:
+ * 1. Start and listen on a Unix socket
+ * 2. Accept connections and handle NDJSON protocol
+ * 3. Authenticate clients with token
+ * 4. Respond to hello requests
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { connect, type Socket } from "node:net";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+	type HelloResponse,
+	type IpcRequest,
+	type IpcResponse,
+	PROTOCOL_VERSION,
+} from "../lib/terminal-host/types";
+
+// Test uses development paths
+const SUPERSET_DIR_NAME = ".superset-dev";
+const SUPERSET_HOME_DIR = join(homedir(), SUPERSET_DIR_NAME);
+const SOCKET_PATH = join(SUPERSET_HOME_DIR, "terminal-host.sock");
+const TOKEN_PATH = join(SUPERSET_HOME_DIR, "terminal-host.token");
+const PID_PATH = join(SUPERSET_HOME_DIR, "terminal-host.pid");
+
+// Path to the daemon source file
+const DAEMON_PATH = resolve(__dirname, "index.ts");
+
+// Timeout for daemon operations
+const DAEMON_TIMEOUT = 10000;
+const CONNECT_TIMEOUT = 5000;
+
+describe("Terminal Host Daemon", () => {
+	let daemonProcess: ChildProcess | null = null;
+
+	/**
+	 * Clean up any existing daemon artifacts
+	 */
+	function cleanup() {
+		// Kill any existing daemon
+		if (existsSync(PID_PATH)) {
+			try {
+				const pid = Number.parseInt(readFileSync(PID_PATH, "utf-8").trim(), 10);
+				if (pid > 0) {
+					process.kill(pid, "SIGTERM");
+				}
+			} catch {
+				// Process might not exist
+			}
+		}
+
+		// Remove socket file
+		if (existsSync(SOCKET_PATH)) {
+			try {
+				rmSync(SOCKET_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+
+		// Remove PID file
+		if (existsSync(PID_PATH)) {
+			try {
+				rmSync(PID_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+
+		// Remove token file (so we get a fresh one)
+		if (existsSync(TOKEN_PATH)) {
+			try {
+				rmSync(TOKEN_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+	}
+
+	/**
+	 * Start the daemon process
+	 */
+	async function startDaemon(): Promise<void> {
+		return new Promise((resolve, reject) => {
+			// Ensure home directory exists
+			if (!existsSync(SUPERSET_HOME_DIR)) {
+				mkdirSync(SUPERSET_HOME_DIR, { recursive: true, mode: 0o700 });
+			}
+
+			// Start daemon with tsx (bun's typescript runner)
+			daemonProcess = spawn("bun", ["run", DAEMON_PATH], {
+				env: {
+					...process.env,
+					NODE_ENV: "development",
+				},
+				stdio: ["ignore", "pipe", "pipe"],
+				detached: true,
+			});
+
+			let output = "";
+
+			daemonProcess.stdout?.on("data", (data) => {
+				output += data.toString();
+				// Check if daemon is ready
+				if (output.includes("Daemon started")) {
+					resolve();
+				}
+			});
+
+			daemonProcess.stderr?.on("data", (data) => {
+				console.error("Daemon stderr:", data.toString());
+			});
+
+			daemonProcess.on("error", (error) => {
+				reject(new Error(`Failed to start daemon: ${error.message}`));
+			});
+
+			daemonProcess.on("exit", (code, signal) => {
+				if (code !== 0 && code !== null) {
+					reject(
+						new Error(`Daemon exited with code ${code}, signal ${signal}`),
+					);
+				}
+			});
+
+			// Timeout if daemon doesn't start
+			setTimeout(() => {
+				reject(
+					new Error(
+						`Daemon failed to start within ${DAEMON_TIMEOUT}ms. Output: ${output}`,
+					),
+				);
+			}, DAEMON_TIMEOUT);
+		});
+	}
+
+	/**
+	 * Stop the daemon process
+	 */
+	async function stopDaemon(): Promise<void> {
+		if (daemonProcess) {
+			return new Promise((resolve) => {
+				daemonProcess?.on("exit", () => {
+					daemonProcess = null;
+					resolve();
+				});
+
+				daemonProcess?.kill("SIGTERM");
+
+				// Force kill if it doesn't exit gracefully
+				setTimeout(() => {
+					if (daemonProcess) {
+						daemonProcess.kill("SIGKILL");
+						daemonProcess = null;
+						resolve();
+					}
+				}, 2000);
+			});
+		}
+	}
+
+	/**
+	 * Connect to the daemon socket
+	 */
+	function connectToDaemon(): Promise<Socket> {
+		return new Promise((resolve, reject) => {
+			const socket = connect(SOCKET_PATH);
+
+			socket.on("connect", () => {
+				resolve(socket);
+			});
+
+			socket.on("error", (error) => {
+				reject(new Error(`Failed to connect to daemon: ${error.message}`));
+			});
+
+			setTimeout(() => {
+				reject(new Error(`Connection timed out after ${CONNECT_TIMEOUT}ms`));
+			}, CONNECT_TIMEOUT);
+		});
+	}
+
+	/**
+	 * Send a request and wait for response
+	 */
+	function sendRequest(
+		socket: Socket,
+		request: IpcRequest,
+	): Promise<IpcResponse> {
+		return new Promise((resolve, reject) => {
+			let buffer = "";
+
+			const onData = (data: Buffer) => {
+				buffer += data.toString();
+				const newlineIndex = buffer.indexOf("\n");
+				if (newlineIndex !== -1) {
+					const line = buffer.slice(0, newlineIndex);
+					socket.off("data", onData);
+					try {
+						resolve(JSON.parse(line));
+					} catch (_error) {
+						reject(new Error(`Failed to parse response: ${line}`));
+					}
+				}
+			};
+
+			socket.on("data", onData);
+
+			socket.write(`${JSON.stringify(request)}\n`);
+
+			setTimeout(() => {
+				socket.off("data", onData);
+				reject(new Error("Request timed out"));
+			}, 5000);
+		});
+	}
+
+	beforeEach(async () => {
+		cleanup();
+		await startDaemon();
+	});
+
+	afterEach(async () => {
+		await stopDaemon();
+		cleanup();
+	});
+
+	describe("hello handshake", () => {
+		it("should accept valid hello request with correct token", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				// Read the token that the daemon generated
+				const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+				expect(token).toHaveLength(64); // 32 bytes = 64 hex chars
+
+				// Send hello request
+				const request: IpcRequest = {
+					id: "test-1",
+					type: "hello",
+					payload: {
+						token,
+						protocolVersion: PROTOCOL_VERSION,
+					},
+				};
+
+				const response = await sendRequest(socket, request);
+
+				expect(response.id).toBe("test-1");
+				expect(response.ok).toBe(true);
+
+				if (response.ok) {
+					const payload = response.payload as HelloResponse;
+					expect(payload.protocolVersion).toBe(PROTOCOL_VERSION);
+					expect(payload.daemonVersion).toBe("1.0.0");
+					expect(payload.daemonPid).toBeGreaterThan(0);
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		it("should reject hello request with invalid token", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				const request: IpcRequest = {
+					id: "test-2",
+					type: "hello",
+					payload: {
+						token: "invalid-token",
+						protocolVersion: PROTOCOL_VERSION,
+					},
+				};
+
+				const response = await sendRequest(socket, request);
+
+				expect(response.id).toBe("test-2");
+				expect(response.ok).toBe(false);
+
+				if (!response.ok) {
+					expect(response.error.code).toBe("AUTH_FAILED");
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		it("should reject hello request with wrong protocol version", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+
+				const request: IpcRequest = {
+					id: "test-3",
+					type: "hello",
+					payload: {
+						token,
+						protocolVersion: 999, // Invalid version
+					},
+				};
+
+				const response = await sendRequest(socket, request);
+
+				expect(response.id).toBe("test-3");
+				expect(response.ok).toBe(false);
+
+				if (!response.ok) {
+					expect(response.error.code).toBe("PROTOCOL_MISMATCH");
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+
+	describe("authentication requirement", () => {
+		it("should reject requests before authentication", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				// Try to list sessions without authenticating first
+				const request: IpcRequest = {
+					id: "test-4",
+					type: "listSessions",
+					payload: undefined,
+				};
+
+				const response = await sendRequest(socket, request);
+
+				expect(response.id).toBe("test-4");
+				expect(response.ok).toBe(false);
+
+				if (!response.ok) {
+					expect(response.error.code).toBe("NOT_AUTHENTICATED");
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		it("should allow listSessions after authentication", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+
+				// Authenticate first
+				const helloRequest: IpcRequest = {
+					id: "test-5a",
+					type: "hello",
+					payload: {
+						token,
+						protocolVersion: PROTOCOL_VERSION,
+					},
+				};
+
+				const helloResponse = await sendRequest(socket, helloRequest);
+				expect(helloResponse.ok).toBe(true);
+
+				// Now list sessions
+				const listRequest: IpcRequest = {
+					id: "test-5b",
+					type: "listSessions",
+					payload: undefined,
+				};
+
+				const listResponse = await sendRequest(socket, listRequest);
+
+				expect(listResponse.id).toBe("test-5b");
+				expect(listResponse.ok).toBe(true);
+
+				if (listResponse.ok) {
+					const payload = listResponse.payload as { sessions: unknown[] };
+					expect(payload.sessions).toEqual([]);
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+
+	describe("unknown requests", () => {
+		it("should return error for unknown request type", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+
+				// Authenticate first
+				const helloRequest: IpcRequest = {
+					id: "test-6a",
+					type: "hello",
+					payload: {
+						token,
+						protocolVersion: PROTOCOL_VERSION,
+					},
+				};
+
+				await sendRequest(socket, helloRequest);
+
+				// Send unknown request
+				const unknownRequest: IpcRequest = {
+					id: "test-6b",
+					type: "unknownRequestType",
+					payload: {},
+				};
+
+				const response = await sendRequest(socket, unknownRequest);
+
+				expect(response.id).toBe("test-6b");
+				expect(response.ok).toBe(false);
+
+				if (!response.ok) {
+					expect(response.error.code).toBe("UNKNOWN_REQUEST");
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+});
diff --git a/apps/desktop/src/main/terminal-host/index.ts b/apps/desktop/src/main/terminal-host/index.ts
new file mode 100644
index 00000000000..f4a92d144f0
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/index.ts
@@ -0,0 +1,631 @@
+/**
+ * Terminal Host Daemon
+ *
+ * A persistent background process that owns PTYs and terminal emulator state.
+ * This allows terminal sessions to survive app restarts and updates.
+ *
+ * Run with: ELECTRON_RUN_AS_NODE=1 electron dist/main/terminal-host.js
+ *
+ * IPC Protocol:
+ * - Uses NDJSON (newline-delimited JSON) over Unix domain socket
+ * - Socket: ~/.superset/terminal-host.sock
+ * - Auth token: ~/.superset/terminal-host.token
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+	type ClearScrollbackRequest,
+	type CreateOrAttachRequest,
+	type DetachRequest,
+	type HelloRequest,
+	type HelloResponse,
+	type IpcErrorResponse,
+	type IpcEvent,
+	type IpcRequest,
+	type IpcSuccessResponse,
+	type KillAllRequest,
+	type KillRequest,
+	PROTOCOL_VERSION,
+	type ResizeRequest,
+	type ShutdownRequest,
+	type TerminalErrorEvent,
+	type WriteRequest,
+} from "../lib/terminal-host/types";
+import { TerminalHost } from "./terminal-host";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const DAEMON_VERSION = "1.0.0";
+
+// Determine superset directory based on NODE_ENV
+const SUPERSET_DIR_NAME =
+	process.env.NODE_ENV === "development" ? ".superset-dev" : ".superset";
+const SUPERSET_HOME_DIR = join(homedir(), SUPERSET_DIR_NAME);
+
+// Socket and token paths
+const SOCKET_PATH = join(SUPERSET_HOME_DIR, "terminal-host.sock");
+const TOKEN_PATH = join(SUPERSET_HOME_DIR, "terminal-host.token");
+const PID_PATH = join(SUPERSET_HOME_DIR, "terminal-host.pid");
+
+// =============================================================================
+// Logging
+// =============================================================================
+
+function log(
+	level: "info" | "warn" | "error",
+	message: string,
+	data?: unknown,
+) {
+	const timestamp = new Date().toISOString();
+	const prefix = `[${timestamp}] [terminal-host] [${level.toUpperCase()}]`;
+	if (data !== undefined) {
+		console.log(`${prefix} ${message}`, data);
+	} else {
+		console.log(`${prefix} ${message}`);
+	}
+}
+
+// =============================================================================
+// Token Management
+// =============================================================================
+
+let authToken: string;
+
+function ensureAuthToken(): string {
+	if (existsSync(TOKEN_PATH)) {
+		// Read existing token
+		return readFileSync(TOKEN_PATH, "utf-8").trim();
+	}
+
+	// Generate new token (32 bytes = 64 hex chars)
+	const token = randomBytes(32).toString("hex");
+	writeFileSync(TOKEN_PATH, token, { mode: 0o600 });
+	log("info", "Generated new auth token");
+	return token;
+}
+
+function validateToken(token: string): boolean {
+	return token === authToken;
+}
+
+// =============================================================================
+// NDJSON Framing
+// =============================================================================
+
+class NdjsonParser {
+	private buffer = "";
+
+	parse(chunk: string): IpcRequest[] {
+		this.buffer += chunk;
+		const messages: IpcRequest[] = [];
+
+		let newlineIndex = this.buffer.indexOf("\n");
+		while (newlineIndex !== -1) {
+			const line = this.buffer.slice(0, newlineIndex);
+			this.buffer = this.buffer.slice(newlineIndex + 1);
+
+			if (line.trim()) {
+				try {
+					messages.push(JSON.parse(line));
+				} catch {
+					// Truncate and redact potentially sensitive data in error logs
+					const maxLen = 100;
+					const truncated =
+						line.length > maxLen
+							? `${line.slice(0, maxLen)}... (truncated)`
+							: line;
+					// Redact anything that looks like a token or secret
+					const redacted = truncated.replace(
+						/["']?(?:token|secret|password|key|auth)["']?\s*[:=]\s*["']?[^"'\s,}]+["']?/gi,
+						"[REDACTED]",
+					);
+					log("warn", "Failed to parse NDJSON line", {
+						preview: redacted,
+						length: line.length,
+					});
+				}
+			}
+
+			newlineIndex = this.buffer.indexOf("\n");
+		}
+
+		return messages;
+	}
+}
+
+function sendResponse(
+	socket: Socket,
+	response: IpcSuccessResponse | IpcErrorResponse,
+) {
+	socket.write(`${JSON.stringify(response)}\n`);
+}
+
+function sendSuccess(socket: Socket, id: string, payload: unknown) {
+	sendResponse(socket, { id, ok: true, payload });
+}
+
+function sendError(socket: Socket, id: string, code: string, message: string) {
+	sendResponse(socket, { id, ok: false, error: { code, message } });
+}
+
+// =============================================================================
+// Terminal Host Instance
+// =============================================================================
+
+let terminalHost: TerminalHost;
+
+// =============================================================================
+// Request Handlers
+// =============================================================================
+
+type RequestHandler = (
+	socket: Socket,
+	id: string,
+	payload: unknown,
+	clientState: ClientState,
+) => void;
+
+interface ClientState {
+	authenticated: boolean;
+}
+
+const handlers: Record<string, RequestHandler> = {
+	hello: (socket, id, payload, clientState) => {
+		const request = payload as HelloRequest;
+
+		// Validate protocol version
+		if (request.protocolVersion !== PROTOCOL_VERSION) {
+			sendError(
+				socket,
+				id,
+				"PROTOCOL_MISMATCH",
+				`Protocol version mismatch. Expected ${PROTOCOL_VERSION}, got ${request.protocolVersion}`,
+			);
+			return;
+		}
+
+		// Validate token
+		if (!validateToken(request.token)) {
+			sendError(socket, id, "AUTH_FAILED", "Invalid auth token");
+			return;
+		}
+
+		clientState.authenticated = true;
+
+		const response: HelloResponse = {
+			protocolVersion: PROTOCOL_VERSION,
+			daemonVersion: DAEMON_VERSION,
+			daemonPid: process.pid,
+		};
+
+		sendSuccess(socket, id, response);
+		log("info", "Client authenticated successfully");
+	},
+
+	createOrAttach: async (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as CreateOrAttachRequest;
+		log("info", `Creating/attaching session: ${request.sessionId}`);
+
+		try {
+			const response = await terminalHost.createOrAttach(socket, request);
+			sendSuccess(socket, id, response);
+
+			log(
+				"info",
+				`Session ${request.sessionId} ${response.isNew ? "created" : "attached"}`,
+			);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			sendError(socket, id, "CREATE_ATTACH_FAILED", message);
+			log("error", `Failed to create/attach session: ${message}`);
+		}
+	},
+
+	write: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as WriteRequest;
+
+		const isNotify = id.startsWith("notify_");
+
+		try {
+			const response = terminalHost.write(request);
+			// High-frequency write notifications don't need responses; suppress to avoid
+			// saturating the socket and dropping input under load.
+			if (!isNotify) {
+				sendSuccess(socket, id, response);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Write failed";
+
+			if (isNotify) {
+				// Emit a session-scoped error event so the main process can surface it.
+				// (No response is sent for notify writes.)
+				const event: IpcEvent = {
+					type: "event",
+					event: "error",
+					sessionId: request.sessionId,
+					payload: {
+						type: "error",
+						error: message,
+						code: "WRITE_FAILED",
+					} satisfies TerminalErrorEvent,
+				};
+				socket.write(`${JSON.stringify(event)}\n`);
+				log("warn", `Write failed for ${request.sessionId}`, {
+					error: message,
+				});
+				return;
+			}
+
+			sendError(socket, id, "WRITE_FAILED", message);
+		}
+	},
+
+	resize: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as ResizeRequest;
+		const response = terminalHost.resize(request);
+		sendSuccess(socket, id, response);
+	},
+
+	detach: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as DetachRequest;
+		const response = terminalHost.detach(socket, request);
+		sendSuccess(socket, id, response);
+	},
+
+	kill: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as KillRequest;
+		const response = terminalHost.kill(request);
+		sendSuccess(socket, id, response);
+		log("info", `Session ${request.sessionId} killed`);
+	},
+
+	killAll: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as KillAllRequest;
+		const response = terminalHost.killAll(request);
+		sendSuccess(socket, id, response);
+		log("info", "All sessions killed");
+	},
+
+	listSessions: (socket, id, _payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const response = terminalHost.listSessions();
+		sendSuccess(socket, id, response);
+	},
+
+	clearScrollback: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as ClearScrollbackRequest;
+		const response = terminalHost.clearScrollback(request);
+		sendSuccess(socket, id, response);
+	},
+
+	shutdown: (socket, id, payload, clientState) => {
+		if (!clientState.authenticated) {
+			sendError(socket, id, "NOT_AUTHENTICATED", "Must authenticate first");
+			return;
+		}
+
+		const request = payload as ShutdownRequest;
+		log("info", "Shutdown requested via IPC", {
+			killSessions: request.killSessions,
+		});
+
+		// Send success response before shutting down
+		sendSuccess(socket, id, { success: true });
+
+		// Kill sessions if requested
+		if (request.killSessions) {
+			terminalHost.killAll({ deleteHistory: false });
+		}
+
+		// Schedule shutdown after a brief delay to allow response to be sent
+		setTimeout(() => {
+			stopServer().then(() => process.exit(0));
+		}, 100);
+	},
+};
+
+function handleRequest(
+	socket: Socket,
+	request: IpcRequest,
+	clientState: ClientState,
+) {
+	const handler = handlers[request.type];
+
+	if (!handler) {
+		sendError(
+			socket,
+			request.id,
+			"UNKNOWN_REQUEST",
+			`Unknown request type: ${request.type}`,
+		);
+		return;
+	}
+
+	try {
+		handler(socket, request.id, request.payload, clientState);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		sendError(socket, request.id, "INTERNAL_ERROR", message);
+		log("error", `Handler error for ${request.type}`, { error: message });
+	}
+}
+
+// =============================================================================
+// Socket Server
+// =============================================================================
+
+let server: Server | null = null;
+
+function handleConnection(socket: Socket) {
+	const parser = new NdjsonParser();
+	const clientState: ClientState = { authenticated: false };
+	const remoteId = `${socket.remoteAddress || "local"}:${Date.now()}`;
+
+	log("info", `Client connected: ${remoteId}`);
+
+	socket.setEncoding("utf-8");
+
+	socket.on("data", (data: string) => {
+		const messages = parser.parse(data);
+		for (const message of messages) {
+			handleRequest(socket, message, clientState);
+		}
+	});
+
+	const handleDisconnect = () => {
+		log("info", `Client disconnected: ${remoteId}`);
+		// Detach this socket from all sessions it was attached to
+		// This is centralized here to avoid per-session socket listeners
+		terminalHost.detachFromAllSessions(socket);
+	};
+
+	socket.on("close", handleDisconnect);
+
+	socket.on("error", (error) => {
+		log("error", `Socket error for ${remoteId}`, { error: error.message });
+	});
+}
+
+/**
+ * Check if there's an active daemon listening on the socket.
+ * Returns true if socket is live and responding.
+ */
+function isSocketLive(): Promise<boolean> {
+	return new Promise((resolve) => {
+		if (!existsSync(SOCKET_PATH)) {
+			resolve(false);
+			return;
+		}
+
+		const testSocket = new (require("node:net").Socket)();
+		const timeout = setTimeout(() => {
+			testSocket.destroy();
+			resolve(false);
+		}, 1000);
+
+		testSocket.on("connect", () => {
+			clearTimeout(timeout);
+			testSocket.destroy();
+			resolve(true);
+		});
+
+		testSocket.on("error", () => {
+			clearTimeout(timeout);
+			resolve(false);
+		});
+
+		testSocket.connect(SOCKET_PATH);
+	});
+}
+
+async function startServer(): Promise<void> {
+	// Ensure superset directory exists with proper permissions
+	if (!existsSync(SUPERSET_HOME_DIR)) {
+		mkdirSync(SUPERSET_HOME_DIR, { recursive: true, mode: 0o700 });
+		log("info", `Created directory: ${SUPERSET_HOME_DIR}`);
+	}
+
+	// Ensure directory has correct permissions
+	try {
+		chmodSync(SUPERSET_HOME_DIR, 0o700);
+	} catch {
+		// May fail if not owner, that's okay
+	}
+
+	// Check if socket is live before removing it
+	// This prevents orphaning a running daemon
+	if (existsSync(SOCKET_PATH)) {
+		const isLive = await isSocketLive();
+		if (isLive) {
+			log("error", "Another daemon is already running and responsive");
+			throw new Error("Another daemon is already running");
+		}
+
+		// Socket exists but not responsive - safe to remove
+		try {
+			unlinkSync(SOCKET_PATH);
+			log("info", "Removed stale socket file");
+		} catch (error) {
+			throw new Error(`Failed to remove stale socket: ${error}`);
+		}
+	}
+
+	// Clean up stale PID file if socket was removed
+	if (existsSync(PID_PATH)) {
+		try {
+			unlinkSync(PID_PATH);
+		} catch {
+			// Ignore - may not have permission
+		}
+	}
+
+	// Initialize auth token
+	authToken = ensureAuthToken();
+
+	// Initialize terminal host
+	terminalHost = new TerminalHost();
+
+	// Create server
+	const newServer = createServer(handleConnection);
+	server = newServer;
+
+	// Wrap server.listen in a Promise for async/await
+	await new Promise<void>((resolve, reject) => {
+		newServer.on("error", (error: NodeJS.ErrnoException) => {
+			if (error.code === "EADDRINUSE") {
+				log("error", "Socket already in use - another daemon may be running");
+				reject(new Error("Socket already in use"));
+			} else {
+				log("error", "Server error", { error: error.message });
+				reject(error);
+			}
+		});
+
+		newServer.listen(SOCKET_PATH, () => {
+			// Set socket permissions (readable/writable by owner only)
+			try {
+				chmodSync(SOCKET_PATH, 0o600);
+			} catch {
+				// May fail on some systems, that's okay - directory permissions protect us
+			}
+
+			// Write PID file
+			writeFileSync(PID_PATH, String(process.pid), { mode: 0o600 });
+
+			log("info", `Daemon started`);
+			log("info", `Socket: ${SOCKET_PATH}`);
+			log("info", `PID: ${process.pid}`);
+			resolve();
+		});
+	});
+}
+
+function stopServer(): Promise<void> {
+	return new Promise((resolve) => {
+		// Dispose terminal host (kills all sessions)
+		if (terminalHost) {
+			terminalHost.dispose();
+			log("info", "Terminal host disposed");
+		}
+
+		if (server) {
+			server.close(() => {
+				log("info", "Server closed");
+				resolve();
+			});
+		} else {
+			resolve();
+		}
+
+		// Clean up socket and PID files
+		try {
+			if (existsSync(SOCKET_PATH)) unlinkSync(SOCKET_PATH);
+			if (existsSync(PID_PATH)) unlinkSync(PID_PATH);
+		} catch {
+			// Best effort cleanup
+		}
+	});
+}
+
+// =============================================================================
+// Signal Handling
+// =============================================================================
+
+function setupSignalHandlers() {
+	const shutdown = async (signal: string) => {
+		log("info", `Received ${signal}, shutting down...`);
+		await stopServer();
+		process.exit(0);
+	};
+
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+	process.on("SIGHUP", () => shutdown("SIGHUP"));
+
+	// Handle uncaught errors
+	process.on("uncaughtException", (error) => {
+		log("error", "Uncaught exception", {
+			error: error.message,
+			stack: error.stack,
+		});
+		stopServer().then(() => process.exit(1));
+	});
+
+	process.on("unhandledRejection", (reason) => {
+		log("error", "Unhandled rejection", { reason });
+		stopServer().then(() => process.exit(1));
+	});
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+	log("info", "Terminal Host Daemon starting...");
+	log("info", `Environment: ${process.env.NODE_ENV || "production"}`);
+	log("info", `Home directory: ${SUPERSET_HOME_DIR}`);
+
+	setupSignalHandlers();
+
+	try {
+		await startServer();
+	} catch (error) {
+		log("error", "Failed to start server", { error });
+		process.exit(1);
+	}
+}
+
+main();
diff --git a/apps/desktop/src/main/terminal-host/pty-subprocess-ipc.ts b/apps/desktop/src/main/terminal-host/pty-subprocess-ipc.ts
new file mode 100644
index 00000000000..c4eb0780d1e
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/pty-subprocess-ipc.ts
@@ -0,0 +1,128 @@
+export enum PtySubprocessIpcType {
+	// Daemon -> subprocess commands
+	Spawn = 1,
+	Write = 2,
+	Resize = 3,
+	Kill = 4,
+	Dispose = 5,
+
+	// Subprocess -> daemon events
+	Ready = 101,
+	Spawned = 102,
+	Data = 103,
+	Exit = 104,
+	Error = 105,
+}
+
+export interface PtySubprocessFrame {
+	type: PtySubprocessIpcType;
+	payload: Buffer;
+}
+
+const HEADER_BYTES = 5;
+const EMPTY_PAYLOAD = Buffer.alloc(0);
+
+// Hard cap to avoid OOM if the stream is corrupted.
+// PTY data is untrusted input in practice (terminal apps can emit arbitrarily).
+const MAX_FRAME_BYTES = 64 * 1024 * 1024; // 64MB
+
+export function createFrameHeader(
+	type: PtySubprocessIpcType,
+	payloadLength: number,
+): Buffer {
+	const header = Buffer.allocUnsafe(HEADER_BYTES);
+	header.writeUInt8(type, 0);
+	header.writeUInt32LE(payloadLength, 1);
+	return header;
+}
+
+export function writeFrame(
+	writable: NodeJS.WritableStream,
+	type: PtySubprocessIpcType,
+	payload?: Buffer,
+): boolean {
+	const payloadBuffer = payload ?? EMPTY_PAYLOAD;
+	const header = createFrameHeader(type, payloadBuffer.length);
+
+	let canWrite = writable.write(header);
+
+	// Always write payload even if the header write returns false.
+	// Backpressure is represented by the return value + 'drain' events.
+	if (payloadBuffer.length > 0) {
+		canWrite = writable.write(payloadBuffer) && canWrite;
+	}
+
+	return canWrite;
+}
+
+export class PtySubprocessFrameDecoder {
+	private header = Buffer.allocUnsafe(HEADER_BYTES);
+	private headerOffset = 0;
+	private frameType: PtySubprocessIpcType | null = null;
+	private payload: Buffer | null = null;
+	private payloadOffset = 0;
+
+	push(chunk: Buffer): PtySubprocessFrame[] {
+		const frames: PtySubprocessFrame[] = [];
+
+		let offset = 0;
+		while (offset < chunk.length) {
+			if (this.payload === null) {
+				const headerNeeded = HEADER_BYTES - this.headerOffset;
+				const available = chunk.length - offset;
+				const toCopy = Math.min(headerNeeded, available);
+
+				chunk.copy(this.header, this.headerOffset, offset, offset + toCopy);
+				this.headerOffset += toCopy;
+				offset += toCopy;
+
+				if (this.headerOffset < HEADER_BYTES) {
+					continue;
+				}
+
+				const type = this.header.readUInt8(0) as PtySubprocessIpcType;
+				const payloadLength = this.header.readUInt32LE(1);
+
+				if (payloadLength > MAX_FRAME_BYTES) {
+					throw new Error(
+						`PtySubprocess IPC frame too large: ${payloadLength} bytes`,
+					);
+				}
+
+				this.frameType = type;
+				this.payload =
+					payloadLength > 0 ? Buffer.allocUnsafe(payloadLength) : null;
+				this.payloadOffset = 0;
+				this.headerOffset = 0;
+
+				if (payloadLength === 0) {
+					frames.push({ type, payload: EMPTY_PAYLOAD });
+					this.frameType = null;
+				}
+			} else {
+				const payloadNeeded = this.payload.length - this.payloadOffset;
+				const available = chunk.length - offset;
+				const toCopy = Math.min(payloadNeeded, available);
+
+				chunk.copy(this.payload, this.payloadOffset, offset, offset + toCopy);
+				this.payloadOffset += toCopy;
+				offset += toCopy;
+
+				if (this.payloadOffset < this.payload.length) {
+					continue;
+				}
+
+				const type = this.frameType ?? PtySubprocessIpcType.Error;
+				const payload = this.payload;
+
+				this.frameType = null;
+				this.payload = null;
+				this.payloadOffset = 0;
+
+				frames.push({ type, payload });
+			}
+		}
+
+		return frames;
+	}
+}
diff --git a/apps/desktop/src/main/terminal-host/pty-subprocess.ts b/apps/desktop/src/main/terminal-host/pty-subprocess.ts
new file mode 100644
index 00000000000..5d3321e952a
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/pty-subprocess.ts
@@ -0,0 +1,460 @@
+/**
+ * PTY Subprocess
+ *
+ * This runs as a completely separate process, owning a single PTY.
+ * Process isolation guarantees that a blocked PTY won't stall the daemon.
+ *
+ * Communication via stdin/stdout using a small binary framing protocol
+ * to avoid JSON escaping overhead on escape-sequence-heavy PTY output.
+ */
+
+import { write as fsWrite } from "node:fs";
+import type { IPty } from "node-pty";
+import * as pty from "node-pty";
+import {
+	PtySubprocessFrameDecoder,
+	PtySubprocessIpcType,
+	writeFrame,
+} from "./pty-subprocess-ipc";
+
+// =============================================================================
+// Types (kept local to avoid bundling/import surprises)
+// =============================================================================
+
+interface SpawnPayload {
+	shell: string;
+	args: string[];
+	cwd: string;
+	cols: number;
+	rows: number;
+	env: Record<string, string>;
+}
+
+// =============================================================================
+// State
+// =============================================================================
+
+let ptyProcess: IPty | null = null;
+let ptyFd: number | null = null;
+
+// Write queue for stdin (uses async fs.write on the PTY fd to avoid blocking the event loop)
+const writeQueue: Buffer[] = [];
+let queuedBytes = 0;
+let flushing = false;
+let writeBackoffMs = 0;
+const MIN_WRITE_BACKOFF_MS = 2;
+const MAX_WRITE_BACKOFF_MS = 50;
+
+let stdinPaused = false;
+const INPUT_QUEUE_HIGH_WATERMARK_BYTES = 8 * 1024 * 1024; // 8MB
+const INPUT_QUEUE_LOW_WATERMARK_BYTES = 4 * 1024 * 1024; // 4MB
+// Hard cap to avoid runaway memory usage if upstream misbehaves.
+const INPUT_QUEUE_HARD_LIMIT_BYTES = 64 * 1024 * 1024; // 64MB
+
+// Output batching - collect PTY output and send periodically.
+// CRITICAL: Use array buffering to avoid O(n²) string concatenation.
+let outputChunks: string[] = [];
+let outputBytesQueued = 0;
+let outputFlushScheduled = false;
+const OUTPUT_FLUSH_INTERVAL_MS = 32; // ~30 fps max
+const MAX_OUTPUT_BATCH_SIZE_BYTES = 128 * 1024; // 128KB max per flush
+
+// Backpressure - track if stdout is draining
+let stdoutDraining = true;
+let ptyPaused = false;
+
+const DEBUG_OUTPUT_BATCHING = process.env.SUPERSET_PTY_SUBPROCESS_DEBUG === "1";
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function send(type: PtySubprocessIpcType, payload?: Buffer): void {
+	stdoutDraining = writeFrame(process.stdout, type, payload);
+
+	// If stdout buffer is full, pause PTY reads (reduces runaway buffering/CPU).
+	if (!stdoutDraining && ptyProcess && !ptyPaused) {
+		ptyPaused = true;
+		ptyProcess.pause();
+	}
+}
+
+process.stdout.on("drain", () => {
+	stdoutDraining = true;
+	if (ptyPaused && ptyProcess) {
+		ptyPaused = false;
+		ptyProcess.resume();
+	}
+});
+
+function sendError(message: string): void {
+	send(PtySubprocessIpcType.Error, Buffer.from(message, "utf8"));
+}
+
+/**
+ * Queue PTY output for batched sending.
+ * Flushes immediately if batch exceeds MAX_OUTPUT_BATCH_SIZE_BYTES.
+ */
+function queueOutput(data: string): void {
+	outputChunks.push(data);
+	outputBytesQueued += Buffer.byteLength(data, "utf8");
+
+	if (outputBytesQueued >= MAX_OUTPUT_BATCH_SIZE_BYTES) {
+		outputFlushScheduled = false;
+		flushOutput();
+		return;
+	}
+
+	if (!outputFlushScheduled) {
+		outputFlushScheduled = true;
+		setTimeout(flushOutput, OUTPUT_FLUSH_INTERVAL_MS);
+	}
+}
+
+function flushOutput(): void {
+	outputFlushScheduled = false;
+	if (outputChunks.length === 0) return;
+
+	const data = outputChunks.join("");
+	const chunkCount = outputChunks.length;
+	outputChunks = [];
+	outputBytesQueued = 0;
+
+	const payload = Buffer.from(data, "utf8");
+
+	if (DEBUG_OUTPUT_BATCHING) {
+		console.error(
+			`[pty-subprocess] Flushing ${payload.length} bytes (${chunkCount} chunks batched)`,
+		);
+	}
+
+	send(PtySubprocessIpcType.Data, payload);
+}
+
+function maybePauseStdin(): void {
+	if (stdinPaused) return;
+	if (queuedBytes < INPUT_QUEUE_HIGH_WATERMARK_BYTES) return;
+
+	stdinPaused = true;
+	process.stdin.pause();
+}
+
+function maybeResumeStdin(): void {
+	if (!stdinPaused) return;
+	if (queuedBytes > INPUT_QUEUE_LOW_WATERMARK_BYTES) return;
+
+	stdinPaused = false;
+	process.stdin.resume();
+}
+
+function queueWriteBuffer(buf: Buffer): void {
+	if (queuedBytes + buf.length > INPUT_QUEUE_HARD_LIMIT_BYTES) {
+		// This should never happen for normal pastes; avoid OOM if it does.
+		sendError("Input backlog exceeded hard limit");
+		return;
+	}
+
+	writeQueue.push(buf);
+	queuedBytes += buf.length;
+	maybePauseStdin();
+	scheduleFlush();
+}
+
+function scheduleFlush(): void {
+	if (flushing) return;
+	flushing = true;
+	setImmediate(flush);
+}
+
+function flush(): void {
+	if (!ptyProcess || writeQueue.length === 0) {
+		flushing = false;
+		return;
+	}
+
+	// If we can access the PTY fd, use async fs.write to avoid blocking the JS event loop.
+	if (typeof ptyFd === "number" && ptyFd > 0) {
+		const buf = writeQueue[0];
+
+		fsWrite(ptyFd, buf, 0, buf.length, null, (err, bytesWritten) => {
+			if (err) {
+				const code = (err as NodeJS.ErrnoException).code;
+				// PTY fds are often non-blocking. If the kernel buffer is full,
+				// writes can fail with EAGAIN/EWOULDBLOCK. This is normal backpressure;
+				// retry later instead of dropping the paste.
+				if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+					writeBackoffMs =
+						writeBackoffMs === 0
+							? MIN_WRITE_BACKOFF_MS
+							: Math.min(writeBackoffMs * 2, MAX_WRITE_BACKOFF_MS);
+					if (
+						DEBUG_OUTPUT_BATCHING &&
+						writeBackoffMs === MIN_WRITE_BACKOFF_MS
+					) {
+						console.error("[pty-subprocess] PTY input backpressured (EAGAIN)");
+					}
+					setTimeout(flush, writeBackoffMs);
+					return;
+				}
+
+				sendError(
+					`Write failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+				writeQueue.length = 0;
+				queuedBytes = 0;
+				flushing = false;
+				return;
+			}
+
+			const wrote = Math.max(0, bytesWritten ?? 0);
+			writeBackoffMs = 0;
+			queuedBytes -= wrote;
+
+			if (wrote >= buf.length) {
+				writeQueue.shift();
+			} else {
+				writeQueue[0] = buf.subarray(wrote);
+			}
+
+			maybeResumeStdin();
+
+			if (writeQueue.length > 0) {
+				setImmediate(flush);
+			} else {
+				flushing = false;
+			}
+		});
+		return;
+	}
+
+	// Fallback: node-pty's write() is synchronous and can block.
+	// This path should rarely be used on macOS, but keep it for safety.
+	const chunk = writeQueue.shift();
+	if (!chunk) {
+		flushing = false;
+		return;
+	}
+
+	queuedBytes -= chunk.length;
+	maybeResumeStdin();
+
+	try {
+		ptyProcess.write(chunk.toString("utf8"));
+	} catch (error) {
+		sendError(
+			`Write failed: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		writeQueue.length = 0;
+		queuedBytes = 0;
+		flushing = false;
+		return;
+	}
+
+	if (writeQueue.length > 0) {
+		setImmediate(flush);
+		return;
+	}
+
+	flushing = false;
+}
+
+// =============================================================================
+// Message Handlers
+// =============================================================================
+
+function handleSpawn(payload: Buffer): void {
+	if (ptyProcess) {
+		sendError("PTY already spawned");
+		return;
+	}
+
+	let msg: SpawnPayload;
+	try {
+		msg = JSON.parse(payload.toString("utf8")) as SpawnPayload;
+	} catch (error) {
+		sendError(
+			`Spawn payload parse failed: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return;
+	}
+
+	try {
+		ptyProcess = pty.spawn(msg.shell, msg.args, {
+			name: "xterm-256color",
+			cols: msg.cols,
+			rows: msg.rows,
+			cwd: msg.cwd,
+			env: msg.env,
+		});
+
+		ptyFd = (ptyProcess as unknown as { fd?: number }).fd ?? null;
+		if (DEBUG_OUTPUT_BATCHING) {
+			console.error(
+				`[pty-subprocess] PTY fd ${ptyFd ?? "unknown"} (${typeof ptyFd === "number" ? "async fs.write enabled" : "falling back to pty.write"})`,
+			);
+		}
+
+		ptyProcess.onData((data) => {
+			queueOutput(data);
+		});
+
+		ptyProcess.onExit(({ exitCode, signal }) => {
+			flushOutput();
+
+			const exitPayload = Buffer.allocUnsafe(8);
+			exitPayload.writeInt32LE(exitCode ?? 0, 0);
+			exitPayload.writeInt32LE(signal ?? 0, 4);
+			send(PtySubprocessIpcType.Exit, exitPayload);
+
+			ptyProcess = null;
+			ptyFd = null;
+			setTimeout(() => {
+				process.exit(0);
+			}, 100);
+		});
+
+		const pidPayload = Buffer.allocUnsafe(4);
+		pidPayload.writeUInt32LE(ptyProcess.pid ?? 0, 0);
+		send(PtySubprocessIpcType.Spawned, pidPayload);
+	} catch (error) {
+		sendError(
+			`Spawn failed: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function handleWrite(payload: Buffer): void {
+	if (!ptyProcess) {
+		sendError("PTY not spawned");
+		return;
+	}
+
+	queueWriteBuffer(payload);
+}
+
+function handleResize(payload: Buffer): void {
+	if (!ptyProcess) return;
+	if (payload.length < 8) return;
+	try {
+		const cols = payload.readUInt32LE(0);
+		const rows = payload.readUInt32LE(4);
+		ptyProcess.resize(cols, rows);
+	} catch {
+		// Ignore resize errors
+	}
+}
+
+function handleKill(payload: Buffer): void {
+	const signal = payload.length > 0 ? payload.toString("utf8") : "SIGTERM";
+
+	if (!ptyProcess) {
+		return;
+	}
+
+	const pid = ptyProcess.pid;
+
+	// Step 1: Send the requested signal (usually SIGTERM for graceful shutdown)
+	try {
+		ptyProcess.kill(signal);
+	} catch {
+		// Process may already be dead
+	}
+
+	// Step 2: Escalate to SIGKILL if still alive after 2 seconds
+	// node-pty's onExit callback may not fire reliably after pty.kill()
+	const escalationTimer = setTimeout(() => {
+		if (!ptyProcess) return; // Already exited via onExit
+
+		try {
+			ptyProcess.kill("SIGKILL");
+		} catch {
+			// Process may already be dead
+		}
+
+		// Step 3: Force completion if onExit still hasn't fired after another 1 second
+		// This ensures the subprocess exits even if node-pty never emits onExit
+		const forceExitTimer = setTimeout(() => {
+			if (!ptyProcess) return; // Finally exited via onExit
+
+			console.error(
+				`[pty-subprocess] Force exit: onExit never fired for pid ${pid}`,
+			);
+
+			// Synthesize Exit frame since onExit won't fire
+			const exitPayload = Buffer.allocUnsafe(8);
+			exitPayload.writeInt32LE(-1, 0); // Unknown exit code
+			exitPayload.writeInt32LE(9, 4); // SIGKILL signal number
+			send(PtySubprocessIpcType.Exit, exitPayload);
+
+			ptyProcess = null;
+			ptyFd = null;
+			process.exit(0);
+		}, 1000);
+		forceExitTimer.unref();
+	}, 2000);
+	escalationTimer.unref();
+}
+
+function handleDispose(): void {
+	flushOutput();
+
+	writeQueue.length = 0;
+	queuedBytes = 0;
+	flushing = false;
+	outputChunks = [];
+	outputBytesQueued = 0;
+	outputFlushScheduled = false;
+	ptyFd = null;
+
+	if (ptyProcess) {
+		try {
+			ptyProcess.kill("SIGKILL");
+		} catch {
+			// Ignore
+		}
+		ptyProcess = null;
+	}
+
+	process.exit(0);
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+const decoder = new PtySubprocessFrameDecoder();
+
+process.stdin.on("data", (chunk: Buffer) => {
+	try {
+		const frames = decoder.push(chunk);
+		for (const frame of frames) {
+			switch (frame.type) {
+				case PtySubprocessIpcType.Spawn:
+					handleSpawn(frame.payload);
+					break;
+				case PtySubprocessIpcType.Write:
+					handleWrite(frame.payload);
+					break;
+				case PtySubprocessIpcType.Resize:
+					handleResize(frame.payload);
+					break;
+				case PtySubprocessIpcType.Kill:
+					handleKill(frame.payload);
+					break;
+				case PtySubprocessIpcType.Dispose:
+					handleDispose();
+					break;
+			}
+		}
+	} catch (error) {
+		sendError(
+			`Failed to parse frame: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+});
+
+process.stdin.on("end", () => {
+	handleDispose();
+});
+
+send(PtySubprocessIpcType.Ready);
diff --git a/apps/desktop/src/main/terminal-host/session-lifecycle.test.ts b/apps/desktop/src/main/terminal-host/session-lifecycle.test.ts
new file mode 100644
index 00000000000..4e994c87957
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/session-lifecycle.test.ts
@@ -0,0 +1,679 @@
+/**
+ * Terminal Host Session Lifecycle Integration Tests
+ *
+ * Tests the full session lifecycle:
+ * 1. Create session with PTY
+ * 2. Write data to terminal
+ * 3. Receive output events
+ * 4. Resize terminal
+ * 5. List sessions
+ * 6. Kill session
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { connect, type Socket } from "node:net";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+	type CreateOrAttachRequest,
+	type CreateOrAttachResponse,
+	type IpcEvent,
+	type IpcRequest,
+	type IpcResponse,
+	type ListSessionsResponse,
+	PROTOCOL_VERSION,
+	type TerminalDataEvent,
+} from "../lib/terminal-host/types";
+
+// Test uses development paths
+const SUPERSET_DIR_NAME = ".superset-dev";
+const SUPERSET_HOME_DIR = join(homedir(), SUPERSET_DIR_NAME);
+const SOCKET_PATH = join(SUPERSET_HOME_DIR, "terminal-host.sock");
+const TOKEN_PATH = join(SUPERSET_HOME_DIR, "terminal-host.token");
+const PID_PATH = join(SUPERSET_HOME_DIR, "terminal-host.pid");
+
+// Path to the daemon source file
+const DAEMON_PATH = resolve(__dirname, "index.ts");
+
+// Timeouts
+const DAEMON_TIMEOUT = 10000;
+const CONNECT_TIMEOUT = 5000;
+
+describe("Terminal Host Session Lifecycle", () => {
+	let daemonProcess: ChildProcess | null = null;
+
+	/**
+	 * Clean up any existing daemon artifacts
+	 */
+	function cleanup() {
+		if (existsSync(PID_PATH)) {
+			try {
+				const pid = Number.parseInt(readFileSync(PID_PATH, "utf-8").trim(), 10);
+				if (pid > 0) {
+					process.kill(pid, "SIGTERM");
+				}
+			} catch {
+				// Process might not exist
+			}
+		}
+
+		if (existsSync(SOCKET_PATH)) {
+			try {
+				rmSync(SOCKET_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+
+		if (existsSync(PID_PATH)) {
+			try {
+				rmSync(PID_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+
+		if (existsSync(TOKEN_PATH)) {
+			try {
+				rmSync(TOKEN_PATH);
+			} catch {
+				// Ignore
+			}
+		}
+	}
+
+	/**
+	 * Start the daemon process
+	 */
+	async function startDaemon(): Promise<void> {
+		return new Promise((resolve, reject) => {
+			if (!existsSync(SUPERSET_HOME_DIR)) {
+				mkdirSync(SUPERSET_HOME_DIR, { recursive: true, mode: 0o700 });
+			}
+
+			daemonProcess = spawn("bun", ["run", DAEMON_PATH], {
+				env: {
+					...process.env,
+					NODE_ENV: "development",
+				},
+				stdio: ["ignore", "pipe", "pipe"],
+				detached: true,
+			});
+
+			let output = "";
+
+			daemonProcess.stdout?.on("data", (data) => {
+				output += data.toString();
+				if (output.includes("Daemon started")) {
+					resolve();
+				}
+			});
+
+			daemonProcess.stderr?.on("data", (data) => {
+				console.error("Daemon stderr:", data.toString());
+			});
+
+			daemonProcess.on("error", (error) => {
+				reject(new Error(`Failed to start daemon: ${error.message}`));
+			});
+
+			daemonProcess.on("exit", (code, signal) => {
+				if (code !== 0 && code !== null) {
+					reject(
+						new Error(`Daemon exited with code ${code}, signal ${signal}`),
+					);
+				}
+			});
+
+			setTimeout(() => {
+				reject(
+					new Error(
+						`Daemon failed to start within ${DAEMON_TIMEOUT}ms. Output: ${output}`,
+					),
+				);
+			}, DAEMON_TIMEOUT);
+		});
+	}
+
+	/**
+	 * Stop the daemon process
+	 */
+	async function stopDaemon(): Promise<void> {
+		if (daemonProcess) {
+			return new Promise((resolve) => {
+				daemonProcess?.on("exit", () => {
+					daemonProcess = null;
+					resolve();
+				});
+
+				daemonProcess?.kill("SIGTERM");
+
+				setTimeout(() => {
+					if (daemonProcess) {
+						daemonProcess.kill("SIGKILL");
+						daemonProcess = null;
+						resolve();
+					}
+				}, 2000);
+			});
+		}
+	}
+
+	/**
+	 * Connect to the daemon socket
+	 */
+	function connectToDaemon(): Promise<Socket> {
+		return new Promise((resolve, reject) => {
+			const socket = connect(SOCKET_PATH);
+
+			socket.on("connect", () => {
+				resolve(socket);
+			});
+
+			socket.on("error", (error) => {
+				reject(new Error(`Failed to connect to daemon: ${error.message}`));
+			});
+
+			setTimeout(() => {
+				reject(new Error(`Connection timed out after ${CONNECT_TIMEOUT}ms`));
+			}, CONNECT_TIMEOUT);
+		});
+	}
+
+	/**
+	 * Send a request and wait for response
+	 */
+	function sendRequest(
+		socket: Socket,
+		request: IpcRequest,
+	): Promise<IpcResponse> {
+		return new Promise((resolve, reject) => {
+			let buffer = "";
+
+			const onData = (data: Buffer) => {
+				buffer += data.toString();
+				const newlineIndex = buffer.indexOf("\n");
+				if (newlineIndex !== -1) {
+					const line = buffer.slice(0, newlineIndex);
+					buffer = buffer.slice(newlineIndex + 1);
+					socket.off("data", onData);
+					try {
+						resolve(JSON.parse(line));
+					} catch (_error) {
+						reject(new Error(`Failed to parse response: ${line}`));
+					}
+				}
+			};
+
+			socket.on("data", onData);
+			socket.write(`${JSON.stringify(request)}\n`);
+
+			setTimeout(() => {
+				socket.off("data", onData);
+				reject(new Error("Request timed out"));
+			}, 5000);
+		});
+	}
+
+	/**
+	 * Wait for a session to be ready (alive and accepting requests)
+	 */
+	async function waitForSessionReady(
+		socket: Socket,
+		sessionId: string,
+		timeoutMs = 3000,
+	): Promise<boolean> {
+		const startTime = Date.now();
+		while (Date.now() - startTime < timeoutMs) {
+			const listRequest: IpcRequest = {
+				id: `list-${Date.now()}`,
+				type: "listSessions",
+				payload: undefined,
+			};
+			const response = await sendRequest(socket, listRequest);
+			if (response.ok) {
+				const payload = response.payload as ListSessionsResponse;
+				const session = payload.sessions.find((s) => s.sessionId === sessionId);
+				if (session?.isAlive) {
+					return true;
+				}
+			}
+			await new Promise((r) => setTimeout(r, 100));
+		}
+		return false;
+	}
+
+	/**
+	 * Authenticate with the daemon
+	 */
+	async function authenticate(socket: Socket): Promise<void> {
+		const token = readFileSync(TOKEN_PATH, "utf-8").trim();
+
+		const request: IpcRequest = {
+			id: `auth-${Date.now()}`,
+			type: "hello",
+			payload: {
+				token,
+				protocolVersion: PROTOCOL_VERSION,
+			},
+		};
+
+		const response = await sendRequest(socket, request);
+		if (!response.ok) {
+			throw new Error(`Authentication failed: ${JSON.stringify(response)}`);
+		}
+	}
+
+	/**
+	 * Wait for events from the socket
+	 */
+	function waitForEvent(
+		socket: Socket,
+		eventType: string,
+		timeout = 5000,
+	): Promise<IpcEvent> {
+		return new Promise((resolve, reject) => {
+			let buffer = "";
+
+			const onData = (data: Buffer) => {
+				buffer += data.toString();
+				let newlineIndex = buffer.indexOf("\n");
+				while (newlineIndex !== -1) {
+					const line = buffer.slice(0, newlineIndex);
+					buffer = buffer.slice(newlineIndex + 1);
+
+					try {
+						const message = JSON.parse(line);
+						if (message.type === "event" && message.event === eventType) {
+							socket.off("data", onData);
+							resolve(message);
+							return;
+						}
+					} catch {
+						// Ignore parse errors
+					}
+
+					newlineIndex = buffer.indexOf("\n");
+				}
+			};
+
+			socket.on("data", onData);
+
+			setTimeout(() => {
+				socket.off("data", onData);
+				reject(new Error(`Event '${eventType}' timed out after ${timeout}ms`));
+			}, timeout);
+		});
+	}
+
+	beforeEach(async () => {
+		cleanup();
+		await startDaemon();
+	});
+
+	afterEach(async () => {
+		await stopDaemon();
+		cleanup();
+	});
+
+	describe("session creation", () => {
+		it("should create a new session and return snapshot", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				const createRequest: IpcRequest = {
+					id: "test-create-1",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-1",
+						workspaceId: "workspace-1",
+						paneId: "pane-1",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				const response = await sendRequest(socket, createRequest);
+
+				expect(response.id).toBe("test-create-1");
+				expect(response.ok).toBe(true);
+
+				if (response.ok) {
+					const payload = response.payload as CreateOrAttachResponse;
+					expect(payload.isNew).toBe(true);
+					expect(payload.snapshot).toBeDefined();
+					expect(payload.snapshot.cols).toBe(80);
+					expect(payload.snapshot.rows).toBe(24);
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		it("should attach to existing session", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create first session
+				const createRequest1: IpcRequest = {
+					id: "test-create-2a",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-2",
+						workspaceId: "workspace-1",
+						paneId: "pane-2",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				const response1 = await sendRequest(socket, createRequest1);
+				expect(response1.ok).toBe(true);
+				if (response1.ok) {
+					expect((response1.payload as CreateOrAttachResponse).isNew).toBe(
+						true,
+					);
+				}
+
+				// Wait for the session to be fully ready before attaching
+				// PTY spawn can be async and session needs to be alive for attach
+				const isReady = await waitForSessionReady(socket, "test-session-2");
+				expect(isReady).toBe(true);
+
+				// Attach to same session
+				const createRequest2: IpcRequest = {
+					id: "test-create-2b",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-2",
+						workspaceId: "workspace-1",
+						paneId: "pane-2",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				const response2 = await sendRequest(socket, createRequest2);
+				if (!response2.ok) {
+					// Log error details for debugging
+					console.error("Attach failed:", JSON.stringify(response2, null, 2));
+				}
+				expect(response2.ok).toBe(true);
+				if (response2.ok) {
+					const payload = response2.payload as CreateOrAttachResponse;
+					expect(payload.isNew).toBe(false);
+					expect(payload.wasRecovered).toBe(true);
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+
+	describe("session operations", () => {
+		// Note: PTY operations may fail in test environment due to bun/node-pty compatibility
+		// The daemon infrastructure is tested separately in daemon.test.ts
+		it.skip("should write data to terminal and receive output", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create session
+				const createRequest: IpcRequest = {
+					id: "test-write-1",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-write",
+						workspaceId: "workspace-1",
+						paneId: "pane-write",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				await sendRequest(socket, createRequest);
+
+				// Wait for shell prompt (data event)
+				const dataPromise = waitForEvent(socket, "data", 10000);
+
+				// Write a simple echo command
+				const writeRequest: IpcRequest = {
+					id: "test-write-2",
+					type: "write",
+					payload: {
+						sessionId: "test-session-write",
+						data: "echo hello\n",
+					},
+				};
+
+				const writeResponse = await sendRequest(socket, writeRequest);
+				if (!writeResponse.ok) {
+					console.error("Write failed:", writeResponse);
+				}
+				expect(writeResponse.ok).toBe(true);
+
+				// Wait for output
+				const event = await dataPromise;
+				expect(event.sessionId).toBe("test-session-write");
+				expect(event.event).toBe("data");
+
+				const payload = event.payload as TerminalDataEvent;
+				expect(payload.type).toBe("data");
+				expect(typeof payload.data).toBe("string");
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		// Note: PTY operations may fail in test environment due to bun/node-pty compatibility
+		it.skip("should resize terminal", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create session
+				const createRequest: IpcRequest = {
+					id: "test-resize-1",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-resize",
+						workspaceId: "workspace-1",
+						paneId: "pane-resize",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				await sendRequest(socket, createRequest);
+
+				// Resize
+				const resizeRequest: IpcRequest = {
+					id: "test-resize-2",
+					type: "resize",
+					payload: {
+						sessionId: "test-session-resize",
+						cols: 120,
+						rows: 40,
+					},
+				};
+
+				const resizeResponse = await sendRequest(socket, resizeRequest);
+				expect(resizeResponse.ok).toBe(true);
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+
+	describe("session listing", () => {
+		// Note: PTY operations may fail in test environment due to bun/node-pty compatibility
+		it.skip("should list all sessions", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create two sessions
+				for (const id of ["session-list-1", "session-list-2"]) {
+					const createRequest: IpcRequest = {
+						id: `create-${id}`,
+						type: "createOrAttach",
+						payload: {
+							sessionId: id,
+							workspaceId: "workspace-1",
+							paneId: `pane-${id}`,
+							tabId: "tab-1",
+							cols: 80,
+							rows: 24,
+							cwd: process.env.HOME,
+						} satisfies CreateOrAttachRequest,
+					};
+					await sendRequest(socket, createRequest);
+				}
+
+				// List sessions
+				const listRequest: IpcRequest = {
+					id: "test-list",
+					type: "listSessions",
+					payload: undefined,
+				};
+
+				const listResponse = await sendRequest(socket, listRequest);
+				expect(listResponse.ok).toBe(true);
+
+				if (listResponse.ok) {
+					const payload = listResponse.payload as ListSessionsResponse;
+					expect(payload.sessions.length).toBeGreaterThanOrEqual(2);
+
+					const sessionIds = payload.sessions.map((s) => s.sessionId);
+					expect(sessionIds).toContain("session-list-1");
+					expect(sessionIds).toContain("session-list-2");
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+
+	describe("session termination", () => {
+		it("should kill a specific session", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create session
+				const createRequest: IpcRequest = {
+					id: "test-kill-1",
+					type: "createOrAttach",
+					payload: {
+						sessionId: "test-session-kill",
+						workspaceId: "workspace-1",
+						paneId: "pane-kill",
+						tabId: "tab-1",
+						cols: 80,
+						rows: 24,
+						cwd: process.env.HOME,
+					} satisfies CreateOrAttachRequest,
+				};
+
+				await sendRequest(socket, createRequest);
+
+				// Kill session
+				const killRequest: IpcRequest = {
+					id: "test-kill-2",
+					type: "kill",
+					payload: {
+						sessionId: "test-session-kill",
+					},
+				};
+
+				const killResponse = await sendRequest(socket, killRequest);
+				expect(killResponse.ok).toBe(true);
+
+				// Wait for exit event
+				const exitEvent = await waitForEvent(socket, "exit", 5000);
+				expect(exitEvent.sessionId).toBe("test-session-kill");
+			} finally {
+				socket.destroy();
+			}
+		});
+
+		// Note: PTY operations may fail in test environment due to bun/node-pty compatibility
+		it.skip("should kill all sessions", async () => {
+			const socket = await connectToDaemon();
+
+			try {
+				await authenticate(socket);
+
+				// Create sessions
+				for (const id of ["kill-all-1", "kill-all-2"]) {
+					const createRequest: IpcRequest = {
+						id: `create-${id}`,
+						type: "createOrAttach",
+						payload: {
+							sessionId: id,
+							workspaceId: "workspace-1",
+							paneId: `pane-${id}`,
+							tabId: "tab-1",
+							cols: 80,
+							rows: 24,
+							cwd: process.env.HOME,
+						} satisfies CreateOrAttachRequest,
+					};
+					await sendRequest(socket, createRequest);
+				}
+
+				// Kill all
+				const killAllRequest: IpcRequest = {
+					id: "test-killall",
+					type: "killAll",
+					payload: {},
+				};
+
+				const killAllResponse = await sendRequest(socket, killAllRequest);
+				expect(killAllResponse.ok).toBe(true);
+
+				// Wait a bit for exits to propagate
+				await new Promise((resolve) => setTimeout(resolve, 1000));
+
+				// List should show no alive sessions
+				const listRequest: IpcRequest = {
+					id: "test-list-after-kill",
+					type: "listSessions",
+					payload: undefined,
+				};
+
+				const listResponse = await sendRequest(socket, listRequest);
+				expect(listResponse.ok).toBe(true);
+
+				if (listResponse.ok) {
+					const payload = listResponse.payload as ListSessionsResponse;
+					const aliveSessions = payload.sessions.filter((s) => s.isAlive);
+					expect(aliveSessions.length).toBe(0);
+				}
+			} finally {
+				socket.destroy();
+			}
+		});
+	});
+});
diff --git a/apps/desktop/src/main/terminal-host/session.ts b/apps/desktop/src/main/terminal-host/session.ts
new file mode 100644
index 00000000000..9b7c95276c7
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/session.ts
@@ -0,0 +1,957 @@
+/**
+ * Terminal Host Session
+ *
+ * A session owns:
+ * - A PTY subprocess (isolates blocking writes from main daemon)
+ * - A HeadlessEmulator instance for state tracking
+ * - A set of attached clients
+ * - Output capture to disk
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import type { Socket } from "node:net";
+import * as path from "node:path";
+import { HeadlessEmulator } from "../lib/terminal-host/headless-emulator";
+import type {
+	CreateOrAttachRequest,
+	IpcEvent,
+	SessionMeta,
+	TerminalDataEvent,
+	TerminalErrorEvent,
+	TerminalExitEvent,
+	TerminalSnapshot,
+} from "../lib/terminal-host/types";
+import {
+	createFrameHeader,
+	PtySubprocessFrameDecoder,
+	PtySubprocessIpcType,
+} from "./pty-subprocess-ipc";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Timeout for flushing emulator writes during attach.
+ * Prevents indefinite hang when continuous output (e.g., tail -f) keeps the queue non-empty.
+ */
+const ATTACH_FLUSH_TIMEOUT_MS = 500;
+
+/**
+ * Maximum bytes allowed in subprocess stdin queue.
+ * Prevents OOM if subprocess stdin is backpressured (e.g., slow PTY consumer).
+ * 2MB is generous - typical large paste is ~50KB.
+ */
+const MAX_SUBPROCESS_STDIN_QUEUE_BYTES = 2_000_000;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SessionOptions {
+	sessionId: string;
+	workspaceId: string;
+	paneId: string;
+	tabId: string;
+	cols: number;
+	rows: number;
+	cwd: string;
+	env?: Record<string, string>;
+	shell?: string;
+	workspaceName?: string;
+	workspacePath?: string;
+	rootPath?: string;
+	scrollbackLines?: number;
+}
+
+export interface AttachedClient {
+	socket: Socket;
+	attachedAt: number;
+}
+
+// =============================================================================
+// Session Class
+// =============================================================================
+
+export class Session {
+	readonly sessionId: string;
+	readonly workspaceId: string;
+	readonly paneId: string;
+	readonly tabId: string;
+	readonly shell: string;
+	readonly createdAt: Date;
+
+	private subprocess: ChildProcess | null = null;
+	private subprocessReady = false;
+	private emulator: HeadlessEmulator;
+	private attachedClients: Map<Socket, AttachedClient> = new Map();
+	private clientSocketsWaitingForDrain: Set<Socket> = new Set();
+	private subprocessStdoutPaused = false;
+	private lastAttachedAt: Date;
+	private exitCode: number | null = null;
+	private disposed = false;
+	private terminatingAt: number | null = null;
+	private subprocessDecoder: PtySubprocessFrameDecoder | null = null;
+	private subprocessStdinQueue: Buffer[] = [];
+	private subprocessStdinQueuedBytes = 0;
+	private subprocessStdinDrainArmed = false;
+
+	// Promise that resolves when PTY is ready to accept writes
+	private ptyReadyPromise: Promise<void>;
+	private ptyReadyResolve: (() => void) | null = null;
+
+	private emulatorWriteQueue: string[] = [];
+	private emulatorWriteQueuedBytes = 0;
+	private emulatorWriteScheduled = false;
+	private emulatorFlushWaiters: Array<() => void> = [];
+
+	// Snapshot boundary tracking - allows capturing consistent state with continuous output
+	private snapshotBoundaryIndex: number | null = null;
+	private snapshotBoundaryWaiters: Array<() => void> = [];
+
+	// Callbacks
+	private onSessionExit?: (
+		sessionId: string,
+		exitCode: number,
+		signal?: number,
+	) => void;
+
+	constructor(options: SessionOptions) {
+		this.sessionId = options.sessionId;
+		this.workspaceId = options.workspaceId;
+		this.paneId = options.paneId;
+		this.tabId = options.tabId;
+		this.shell = options.shell || this.getDefaultShell();
+		this.createdAt = new Date();
+		this.lastAttachedAt = new Date();
+
+		// Initialize PTY ready promise
+		this.ptyReadyPromise = new Promise((resolve) => {
+			this.ptyReadyResolve = resolve;
+		});
+
+		// Create headless emulator
+		this.emulator = new HeadlessEmulator({
+			cols: options.cols,
+			rows: options.rows,
+			scrollback: options.scrollbackLines ?? 10000,
+		});
+
+		// Set initial CWD
+		this.emulator.setCwd(options.cwd);
+
+		// Listen for emulator output (query responses)
+		this.emulator.onData((data) => {
+			// If no clients attached, send responses back to PTY
+			if (
+				this.attachedClients.size === 0 &&
+				this.subprocess &&
+				this.subprocessReady
+			) {
+				this.sendWriteToSubprocess(data);
+			}
+		});
+	}
+
+	/**
+	 * Spawn the PTY process via subprocess
+	 */
+	spawn(options: {
+		cwd: string;
+		cols: number;
+		rows: number;
+		env?: Record<string, string>;
+	}): void {
+		if (this.subprocess) {
+			throw new Error("PTY already spawned");
+		}
+
+		const { cwd, cols, rows, env = {} } = options;
+
+		// Build environment - filter out undefined values and ELECTRON_RUN_AS_NODE
+		const processEnv: Record<string, string> = {};
+		for (const [key, value] of Object.entries(process.env)) {
+			if (key === "ELECTRON_RUN_AS_NODE") continue;
+			if (value !== undefined) {
+				processEnv[key] = value;
+			}
+		}
+		Object.assign(processEnv, env);
+		processEnv.TERM = "xterm-256color";
+
+		// Get shell args
+		const shellArgs = this.getShellArgs(this.shell);
+
+		// Spawn PTY subprocess
+		// The subprocess script is bundled alongside terminal-host.js
+		const subprocessPath = path.join(__dirname, "pty-subprocess.js");
+
+		// Use electron as node to run the subprocess
+		const electronPath = process.execPath;
+		this.subprocess = spawn(electronPath, [subprocessPath], {
+			stdio: ["pipe", "pipe", "inherit"], // pipe stdin/stdout, inherit stderr
+			env: {
+				...process.env,
+				ELECTRON_RUN_AS_NODE: "1",
+			},
+		});
+
+		// Read framed messages from subprocess stdout
+		if (this.subprocess.stdout) {
+			this.subprocessDecoder = new PtySubprocessFrameDecoder();
+			this.subprocess.stdout.on("data", (chunk: Buffer) => {
+				try {
+					const frames = this.subprocessDecoder?.push(chunk) ?? [];
+					for (const frame of frames) {
+						this.handleSubprocessFrame(frame.type, frame.payload);
+					}
+				} catch (error) {
+					console.error(
+						`[Session ${this.sessionId}] Failed to parse subprocess frames:`,
+						error,
+					);
+				}
+			});
+		}
+
+		// Handle subprocess exit
+		this.subprocess.on("exit", (code) => {
+			console.log(
+				`[Session ${this.sessionId}] Subprocess exited with code ${code}`,
+			);
+			this.handleSubprocessExit(code ?? -1);
+		});
+
+		this.subprocess.on("error", (error) => {
+			console.error(`[Session ${this.sessionId}] Subprocess error:`, error);
+			this.handleSubprocessExit(-1);
+		});
+
+		// Store pending spawn config
+		this.pendingSpawn = {
+			shell: this.shell,
+			args: shellArgs,
+			cwd,
+			cols,
+			rows,
+			env: processEnv,
+		};
+	}
+
+	private pendingSpawn: {
+		shell: string;
+		args: string[];
+		cwd: string;
+		cols: number;
+		rows: number;
+		env: Record<string, string>;
+	} | null = null;
+
+	/**
+	 * Handle frames from the PTY subprocess
+	 */
+	private handleSubprocessFrame(
+		type: PtySubprocessIpcType,
+		payload: Buffer,
+	): void {
+		switch (type) {
+			case PtySubprocessIpcType.Ready:
+				this.subprocessReady = true;
+				if (this.pendingSpawn) {
+					this.sendSpawnToSubprocess(this.pendingSpawn);
+					this.pendingSpawn = null;
+				}
+				break;
+
+			case PtySubprocessIpcType.Spawned:
+				this.ptyPid = payload.length >= 4 ? payload.readUInt32LE(0) : null;
+				// Resolve the ready promise so callers can await PTY readiness
+				if (this.ptyReadyResolve) {
+					this.ptyReadyResolve();
+					this.ptyReadyResolve = null;
+				}
+				break;
+
+			case PtySubprocessIpcType.Data: {
+				if (payload.length === 0) break;
+				const data = payload.toString("utf8");
+
+				this.enqueueEmulatorWrite(data);
+
+				this.broadcastEvent("data", {
+					type: "data",
+					data,
+				} satisfies TerminalDataEvent);
+				break;
+			}
+
+			case PtySubprocessIpcType.Exit: {
+				const exitCode = payload.length >= 4 ? payload.readInt32LE(0) : 0;
+				const signal = payload.length >= 8 ? payload.readInt32LE(4) : 0;
+				this.exitCode = exitCode;
+
+				this.broadcastEvent("exit", {
+					type: "exit",
+					exitCode,
+					signal: signal !== 0 ? signal : undefined,
+				} satisfies TerminalExitEvent);
+
+				this.onSessionExit?.(
+					this.sessionId,
+					exitCode,
+					signal !== 0 ? signal : undefined,
+				);
+				break;
+			}
+
+			case PtySubprocessIpcType.Error: {
+				const errorMessage =
+					payload.length > 0
+						? payload.toString("utf8")
+						: "Unknown subprocess error";
+
+				console.error(
+					`[Session ${this.sessionId}] Subprocess error:`,
+					errorMessage,
+				);
+
+				this.broadcastEvent("error", {
+					type: "error",
+					error: errorMessage,
+					code: errorMessage.includes("Write queue full")
+						? "WRITE_QUEUE_FULL"
+						: "SUBPROCESS_ERROR",
+				} satisfies TerminalErrorEvent);
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Handle subprocess exiting
+	 */
+	private handleSubprocessExit(exitCode: number): void {
+		if (this.exitCode === null) {
+			this.exitCode = exitCode;
+
+			this.broadcastEvent("exit", {
+				type: "exit",
+				exitCode,
+			} satisfies TerminalExitEvent);
+
+			this.onSessionExit?.(this.sessionId, exitCode);
+		}
+
+		this.subprocess = null;
+		this.subprocessReady = false;
+		this.subprocessDecoder = null;
+		this.subprocessStdinQueue = [];
+		this.subprocessStdinQueuedBytes = 0;
+		this.subprocessStdinDrainArmed = false;
+		this.subprocessStdoutPaused = false;
+
+		this.emulatorWriteQueue = [];
+		this.emulatorWriteQueuedBytes = 0;
+		this.emulatorWriteScheduled = false;
+		this.snapshotBoundaryIndex = null;
+		const waiters = this.emulatorFlushWaiters;
+		this.emulatorFlushWaiters = [];
+		for (const resolve of waiters) resolve();
+		const boundaryWaiters = this.snapshotBoundaryWaiters;
+		this.snapshotBoundaryWaiters = [];
+		for (const resolve of boundaryWaiters) resolve();
+	}
+
+	/**
+	 * Flush queued frames to subprocess stdin, respecting stream backpressure.
+	 */
+	private flushSubprocessStdinQueue(): void {
+		if (!this.subprocess?.stdin || this.disposed) return;
+
+		while (this.subprocessStdinQueue.length > 0) {
+			const buf = this.subprocessStdinQueue[0];
+			const canWrite = this.subprocess.stdin.write(buf);
+			if (!canWrite) {
+				if (!this.subprocessStdinDrainArmed) {
+					this.subprocessStdinDrainArmed = true;
+					this.subprocess.stdin.once("drain", () => {
+						this.subprocessStdinDrainArmed = false;
+						this.flushSubprocessStdinQueue();
+					});
+				}
+				return;
+			}
+
+			this.subprocessStdinQueue.shift();
+			this.subprocessStdinQueuedBytes -= buf.length;
+		}
+	}
+
+	/**
+	 * Send a frame to the subprocess.
+	 * Returns false if write buffer is full (caller should handle).
+	 */
+	private sendFrameToSubprocess(
+		type: PtySubprocessIpcType,
+		payload?: Buffer,
+	): boolean {
+		if (!this.subprocess?.stdin || this.disposed) return false;
+
+		const payloadBuffer = payload ?? Buffer.alloc(0);
+		const frameSize = 5 + payloadBuffer.length; // 5-byte header + payload
+
+		// Check queue limit to prevent OOM under backpressure
+		if (
+			this.subprocessStdinQueuedBytes + frameSize >
+			MAX_SUBPROCESS_STDIN_QUEUE_BYTES
+		) {
+			console.warn(
+				`[Session ${this.sessionId}] stdin queue full (${this.subprocessStdinQueuedBytes} bytes), dropping frame`,
+			);
+			this.broadcastEvent("error", {
+				type: "error",
+				error: "Write queue full - input dropped",
+				code: "WRITE_QUEUE_FULL",
+			} satisfies TerminalErrorEvent);
+			return false;
+		}
+
+		const header = createFrameHeader(type, payloadBuffer.length);
+
+		this.subprocessStdinQueue.push(header);
+		this.subprocessStdinQueuedBytes += header.length;
+
+		if (payloadBuffer.length > 0) {
+			this.subprocessStdinQueue.push(payloadBuffer);
+			this.subprocessStdinQueuedBytes += payloadBuffer.length;
+		}
+
+		const wasBackpressured = this.subprocessStdinDrainArmed;
+		this.flushSubprocessStdinQueue();
+
+		if (this.subprocessStdinDrainArmed && !wasBackpressured) {
+			console.warn(
+				`[Session ${this.sessionId}] stdin buffer full, write may be delayed`,
+			);
+		}
+
+		return !this.subprocessStdinDrainArmed;
+	}
+
+	private sendSpawnToSubprocess(payload: {
+		shell: string;
+		args: string[];
+		cwd: string;
+		cols: number;
+		rows: number;
+		env: Record<string, string>;
+	}): boolean {
+		return this.sendFrameToSubprocess(
+			PtySubprocessIpcType.Spawn,
+			Buffer.from(JSON.stringify(payload), "utf8"),
+		);
+	}
+
+	private sendWriteToSubprocess(data: string): boolean {
+		// Chunk large writes to avoid allocating/queuing massive single frames.
+		const MAX_CHUNK_CHARS = 8192;
+		let ok = true;
+
+		for (let offset = 0; offset < data.length; offset += MAX_CHUNK_CHARS) {
+			const part = data.slice(offset, offset + MAX_CHUNK_CHARS);
+			ok =
+				this.sendFrameToSubprocess(
+					PtySubprocessIpcType.Write,
+					Buffer.from(part, "utf8"),
+				) && ok;
+		}
+
+		return ok;
+	}
+
+	private sendResizeToSubprocess(cols: number, rows: number): boolean {
+		const payload = Buffer.allocUnsafe(8);
+		payload.writeUInt32LE(cols, 0);
+		payload.writeUInt32LE(rows, 4);
+		return this.sendFrameToSubprocess(PtySubprocessIpcType.Resize, payload);
+	}
+
+	private sendKillToSubprocess(signal?: string): boolean {
+		const payload = signal ? Buffer.from(signal, "utf8") : undefined;
+		return this.sendFrameToSubprocess(PtySubprocessIpcType.Kill, payload);
+	}
+
+	private sendDisposeToSubprocess(): boolean {
+		return this.sendFrameToSubprocess(PtySubprocessIpcType.Dispose);
+	}
+
+	private enqueueEmulatorWrite(data: string): void {
+		this.emulatorWriteQueue.push(data);
+		this.emulatorWriteQueuedBytes += data.length;
+		this.scheduleEmulatorWrite();
+	}
+
+	private scheduleEmulatorWrite(): void {
+		if (this.emulatorWriteScheduled || this.disposed) return;
+		this.emulatorWriteScheduled = true;
+		setImmediate(() => {
+			this.processEmulatorWriteQueue();
+		});
+	}
+
+	private processEmulatorWriteQueue(): void {
+		if (this.disposed) {
+			this.emulatorWriteQueue = [];
+			this.emulatorWriteQueuedBytes = 0;
+			this.emulatorWriteScheduled = false;
+			this.snapshotBoundaryIndex = null;
+			const waiters = this.emulatorFlushWaiters;
+			this.emulatorFlushWaiters = [];
+			for (const resolve of waiters) resolve();
+			const boundaryWaiters = this.snapshotBoundaryWaiters;
+			this.snapshotBoundaryWaiters = [];
+			for (const resolve of boundaryWaiters) resolve();
+			return;
+		}
+
+		const start = performance.now();
+		const hasClients = this.attachedClients.size > 0;
+		const backlogBytes = this.emulatorWriteQueuedBytes;
+
+		// Keep the daemon responsive while still ensuring the emulator catches up eventually.
+		const baseBudgetMs = hasClients ? 5 : 25;
+		const budgetMs =
+			backlogBytes > 1024 * 1024 ? Math.max(baseBudgetMs, 25) : baseBudgetMs;
+		const MAX_CHUNK_CHARS = 8192;
+
+		while (this.emulatorWriteQueue.length > 0) {
+			if (performance.now() - start > budgetMs) break;
+
+			let chunk = this.emulatorWriteQueue[0];
+			if (chunk.length > MAX_CHUNK_CHARS) {
+				this.emulatorWriteQueue[0] = chunk.slice(MAX_CHUNK_CHARS);
+				chunk = chunk.slice(0, MAX_CHUNK_CHARS);
+			} else {
+				this.emulatorWriteQueue.shift();
+
+				// Decrement boundary counter if tracking
+				if (this.snapshotBoundaryIndex !== null) {
+					this.snapshotBoundaryIndex--;
+				}
+			}
+
+			this.emulatorWriteQueuedBytes -= chunk.length;
+			this.emulator.write(chunk);
+
+			// Check if we've reached the snapshot boundary (processed all items up to it)
+			if (this.snapshotBoundaryIndex === 0) {
+				this.snapshotBoundaryIndex = null;
+				const boundaryWaiters = this.snapshotBoundaryWaiters;
+				this.snapshotBoundaryWaiters = [];
+				for (const resolve of boundaryWaiters) resolve();
+				// Continue processing remaining items (arrived after boundary was set)
+				if (this.emulatorWriteQueue.length > 0) {
+					setImmediate(() => {
+						this.processEmulatorWriteQueue();
+					});
+					return;
+				}
+				this.emulatorWriteScheduled = false;
+				const waiters = this.emulatorFlushWaiters;
+				this.emulatorFlushWaiters = [];
+				for (const resolve of waiters) resolve();
+				return;
+			}
+		}
+
+		if (this.emulatorWriteQueue.length > 0) {
+			setImmediate(() => {
+				this.processEmulatorWriteQueue();
+			});
+			return;
+		}
+
+		this.emulatorWriteScheduled = false;
+
+		// If we've drained the queue, any pending boundary is also reached
+		if (this.snapshotBoundaryIndex !== null) {
+			this.snapshotBoundaryIndex = null;
+			const boundaryWaiters = this.snapshotBoundaryWaiters;
+			this.snapshotBoundaryWaiters = [];
+			for (const resolve of boundaryWaiters) resolve();
+		}
+
+		const waiters = this.emulatorFlushWaiters;
+		this.emulatorFlushWaiters = [];
+		for (const resolve of waiters) resolve();
+	}
+
+	/**
+	 * Flush emulator writes up to current queue position (snapshot boundary).
+	 * Unlike flushEmulatorWrites, this captures a consistent point-in-time state
+	 * even with continuous output - we only wait for data received BEFORE this call.
+	 *
+	 * The key insight: snapshotBoundaryIndex tracks how many items REMAIN that
+	 * need to be processed. Each time we shift an item, we decrement it.
+	 * When it reaches 0, we've processed everything up to the boundary.
+	 */
+	private async flushToSnapshotBoundary(timeoutMs: number): Promise<boolean> {
+		// Mark the current queue length as how many items we need to process
+		const itemsToProcess = this.emulatorWriteQueue.length;
+
+		if (itemsToProcess === 0 && !this.emulatorWriteScheduled) {
+			return true; // Already flushed
+		}
+
+		// Set the boundary counter - processEmulatorWriteQueue will decrement this
+		this.snapshotBoundaryIndex = itemsToProcess;
+
+		const boundaryPromise = new Promise<void>((resolve) => {
+			this.snapshotBoundaryWaiters.push(resolve);
+			this.scheduleEmulatorWrite();
+		});
+
+		const timeoutPromise = new Promise<void>((resolve) =>
+			setTimeout(resolve, timeoutMs),
+		);
+
+		await Promise.race([boundaryPromise, timeoutPromise]);
+
+		// Check if we actually reached the boundary or timed out
+		const reachedBoundary = this.snapshotBoundaryIndex === null;
+
+		// Clean up if timed out (boundary wasn't reached)
+		if (!reachedBoundary) {
+			this.snapshotBoundaryIndex = null;
+			// Remove our waiter from the list
+			this.snapshotBoundaryWaiters = [];
+		}
+
+		return reachedBoundary;
+	}
+
+	/**
+	 * Check if session is alive (PTY running)
+	 */
+	get isAlive(): boolean {
+		return this.subprocess !== null && this.exitCode === null;
+	}
+
+	/**
+	 * Check if session is in the process of terminating.
+	 * A terminating session has received a kill signal but hasn't exited yet.
+	 */
+	get isTerminating(): boolean {
+		return this.terminatingAt !== null;
+	}
+
+	/**
+	 * Check if session can be attached to.
+	 * A session is attachable if it's alive and not terminating.
+	 * This prevents race conditions where createOrAttach is called
+	 * immediately after kill but before the PTY has actually exited.
+	 */
+	get isAttachable(): boolean {
+		return this.isAlive && !this.isTerminating;
+	}
+
+	/**
+	 * Wait for PTY to be ready to accept writes.
+	 * Returns immediately if already ready, or waits for Spawned event.
+	 */
+	waitForReady(): Promise<void> {
+		return this.ptyReadyPromise;
+	}
+
+	/**
+	 * Get number of attached clients
+	 */
+	get clientCount(): number {
+		return this.attachedClients.size;
+	}
+
+	/**
+	 * Attach a client to this session
+	 */
+	async attach(socket: Socket): Promise<TerminalSnapshot> {
+		if (this.disposed) {
+			throw new Error("Session disposed");
+		}
+
+		this.attachedClients.set(socket, {
+			socket,
+			attachedAt: Date.now(),
+		});
+		this.lastAttachedAt = new Date();
+
+		// Use snapshot boundary flush for consistent state with continuous output.
+		// This ensures we capture all data received BEFORE attach was called,
+		// even if new data continues to arrive during the flush.
+		const reachedBoundary = await this.flushToSnapshotBoundary(
+			ATTACH_FLUSH_TIMEOUT_MS,
+		);
+
+		if (!reachedBoundary) {
+			console.warn(
+				`[Session ${this.sessionId}] Attach flush timeout after ${ATTACH_FLUSH_TIMEOUT_MS}ms`,
+			);
+		}
+
+		return this.emulator.getSnapshotAsync();
+	}
+
+	/**
+	 * Detach a client from this session
+	 */
+	detach(socket: Socket): void {
+		this.attachedClients.delete(socket);
+		this.clientSocketsWaitingForDrain.delete(socket);
+		this.maybeResumeSubprocessStdout();
+	}
+
+	/**
+	 * Write data to PTY (non-blocking - sent to subprocess)
+	 */
+	write(data: string): void {
+		if (!this.subprocess || !this.subprocessReady) {
+			throw new Error("PTY not spawned");
+		}
+		this.sendWriteToSubprocess(data);
+	}
+
+	/**
+	 * Resize PTY and emulator
+	 */
+	resize(cols: number, rows: number): void {
+		if (this.subprocess && this.subprocessReady) {
+			this.sendResizeToSubprocess(cols, rows);
+		}
+		this.emulator.resize(cols, rows);
+	}
+
+	/**
+	 * Clear scrollback buffer
+	 */
+	clearScrollback(): void {
+		this.emulator.clear();
+	}
+
+	/**
+	 * Get session snapshot
+	 */
+	getSnapshot(): TerminalSnapshot {
+		return this.emulator.getSnapshot();
+	}
+
+	/**
+	 * Get session metadata
+	 */
+	getMeta(): SessionMeta {
+		const dims = this.emulator.getDimensions();
+		return {
+			sessionId: this.sessionId,
+			workspaceId: this.workspaceId,
+			paneId: this.paneId,
+			cwd: this.emulator.getCwd() || "",
+			cols: dims.cols,
+			rows: dims.rows,
+			createdAt: this.createdAt.toISOString(),
+			lastAttachedAt: this.lastAttachedAt.toISOString(),
+			shell: this.shell,
+		};
+	}
+
+	/**
+	 * Kill the PTY process.
+	 * Marks the session as terminating immediately (idempotent).
+	 * The actual PTY termination is async - use isTerminating to check state.
+	 */
+	kill(signal: string = "SIGTERM"): void {
+		// Idempotent: if already terminating, don't send another signal
+		if (this.terminatingAt !== null) {
+			return;
+		}
+
+		// Mark as terminating immediately to prevent race conditions
+		this.terminatingAt = Date.now();
+
+		if (this.subprocess && this.subprocessReady) {
+			this.sendKillToSubprocess(signal);
+			return;
+		}
+
+		// If the subprocess isn't ready yet, fall back to killing the subprocess itself
+		// so session termination is reliable (differentiation isn't meaningful pre-spawn).
+		try {
+			this.subprocess?.kill(signal as NodeJS.Signals);
+		} catch {
+			// Process may already be dead
+		}
+	}
+
+	/**
+	 * Dispose of the session
+	 */
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+
+		if (this.subprocess) {
+			// Capture reference before nullifying - the timeout needs it
+			const subprocess = this.subprocess;
+			this.sendDisposeToSubprocess();
+			// Force kill after timeout if dispose frame didn't terminate it
+			const killTimer = setTimeout(() => {
+				try {
+					subprocess.kill("SIGKILL");
+				} catch {
+					// Process may already be dead
+				}
+			}, 1000);
+			killTimer.unref(); // Don't keep daemon alive for this timer
+			this.subprocess = null;
+		}
+		this.subprocessReady = false;
+		this.subprocessDecoder = null;
+		this.subprocessStdinQueue = [];
+		this.subprocessStdinQueuedBytes = 0;
+		this.subprocessStdinDrainArmed = false;
+
+		this.emulatorWriteQueue = [];
+		this.emulatorWriteQueuedBytes = 0;
+		this.emulatorWriteScheduled = false;
+		this.snapshotBoundaryIndex = null;
+		const waiters = this.emulatorFlushWaiters;
+		this.emulatorFlushWaiters = [];
+		for (const resolve of waiters) resolve();
+		const boundaryWaiters = this.snapshotBoundaryWaiters;
+		this.snapshotBoundaryWaiters = [];
+		for (const resolve of boundaryWaiters) resolve();
+
+		this.emulator.dispose();
+		this.attachedClients.clear();
+		this.clientSocketsWaitingForDrain.clear();
+		this.subprocessStdoutPaused = false;
+	}
+
+	/**
+	 * Set exit callback
+	 */
+	onExit(
+		callback: (sessionId: string, exitCode: number, signal?: number) => void,
+	): void {
+		this.onSessionExit = callback;
+	}
+
+	// ===========================================================================
+	// Private Methods
+	// ===========================================================================
+
+	/**
+	 * Broadcast an event to all attached clients with backpressure awareness.
+	 */
+	private broadcastEvent(
+		eventType: string,
+		payload: TerminalDataEvent | TerminalExitEvent | TerminalErrorEvent,
+	): void {
+		const event: IpcEvent = {
+			type: "event",
+			event: eventType,
+			sessionId: this.sessionId,
+			payload,
+		};
+
+		const message = `${JSON.stringify(event)}\n`;
+
+		for (const { socket } of this.attachedClients.values()) {
+			try {
+				const canWrite = socket.write(message);
+				if (!canWrite) {
+					// Socket buffer full - data will be queued but may cause memory pressure
+					// In production, could track this and pause PTY output temporarily
+					console.warn(
+						`[Session ${this.sessionId}] Client socket buffer full, output may be delayed`,
+					);
+					this.handleClientBackpressure(socket);
+				}
+			} catch {
+				this.attachedClients.delete(socket);
+				this.clientSocketsWaitingForDrain.delete(socket);
+			}
+		}
+	}
+
+	private handleClientBackpressure(socket: Socket): void {
+		// If the client can’t keep up, pause reading from the subprocess stdout.
+		// This will backpressure the subprocess stdout pipe, which in turn pauses
+		// PTY reads inside the subprocess (preventing runaway buffering/CPU).
+		if (!this.subprocessStdoutPaused && this.subprocess?.stdout) {
+			this.subprocessStdoutPaused = true;
+			this.subprocess.stdout.pause();
+		}
+
+		if (this.clientSocketsWaitingForDrain.has(socket)) return;
+		this.clientSocketsWaitingForDrain.add(socket);
+
+		socket.once("drain", () => {
+			this.clientSocketsWaitingForDrain.delete(socket);
+			this.maybeResumeSubprocessStdout();
+		});
+	}
+
+	private maybeResumeSubprocessStdout(): void {
+		if (this.clientSocketsWaitingForDrain.size > 0) return;
+		if (!this.subprocessStdoutPaused) return;
+		if (!this.subprocess?.stdout) return;
+
+		this.subprocessStdoutPaused = false;
+		this.subprocess.stdout.resume();
+	}
+
+	/**
+	 * Get default shell for the platform
+	 */
+	private getDefaultShell(): string {
+		if (process.platform === "win32") {
+			return process.env.COMSPEC || "cmd.exe";
+		}
+		return process.env.SHELL || "/bin/zsh";
+	}
+
+	/**
+	 * Get shell arguments for login shell
+	 */
+	private getShellArgs(shell: string): string[] {
+		const shellName = shell.split("/").pop() || "";
+
+		if (["zsh", "bash", "sh", "ksh", "fish"].includes(shellName)) {
+			return ["-l"];
+		}
+
+		return [];
+	}
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Create a new session from request parameters
+ */
+export function createSession(request: CreateOrAttachRequest): Session {
+	return new Session({
+		sessionId: request.sessionId,
+		workspaceId: request.workspaceId,
+		paneId: request.paneId,
+		tabId: request.tabId,
+		cols: request.cols,
+		rows: request.rows,
+		cwd: request.cwd || process.env.HOME || "/",
+		env: request.env,
+		shell: request.shell,
+		workspaceName: request.workspaceName,
+		workspacePath: request.workspacePath,
+		rootPath: request.rootPath,
+	});
+}
diff --git a/apps/desktop/src/main/terminal-host/terminal-host.ts b/apps/desktop/src/main/terminal-host/terminal-host.ts
new file mode 100644
index 00000000000..5fb7f49c667
--- /dev/null
+++ b/apps/desktop/src/main/terminal-host/terminal-host.ts
@@ -0,0 +1,339 @@
+/**
+ * Terminal Host Manager
+ *
+ * Manages all terminal sessions in the daemon.
+ * Responsible for:
+ * - Session lifecycle (create, attach, detach, kill)
+ * - Session lookup and listing
+ * - Cleanup on shutdown
+ */
+
+import type { Socket } from "node:net";
+import type {
+	ClearScrollbackRequest,
+	CreateOrAttachRequest,
+	CreateOrAttachResponse,
+	DetachRequest,
+	EmptyResponse,
+	KillAllRequest,
+	KillRequest,
+	ListSessionsResponse,
+	ResizeRequest,
+	WriteRequest,
+} from "../lib/terminal-host/types";
+import { createSession, type Session } from "./session";
+
+// =============================================================================
+// TerminalHost Class
+// =============================================================================
+
+/** Timeout for force-disposing sessions that don't exit after kill */
+const KILL_TIMEOUT_MS = 5000;
+
+export class TerminalHost {
+	private sessions: Map<string, Session> = new Map();
+	private killTimers: Map<string, NodeJS.Timeout> = new Map();
+
+	/**
+	 * Create or attach to a terminal session
+	 */
+	async createOrAttach(
+		socket: Socket,
+		request: CreateOrAttachRequest,
+	): Promise<CreateOrAttachResponse> {
+		const { sessionId } = request;
+
+		let session = this.sessions.get(sessionId);
+		let isNew = false;
+
+		// If session is terminating (kill was called but PTY hasn't exited yet),
+		// force-dispose it and create a fresh session. This prevents race conditions
+		// where createOrAttach is called immediately after kill.
+		if (session?.isTerminating) {
+			console.log(
+				`[TerminalHost] Session ${sessionId} is terminating, force-disposing for fresh start`,
+			);
+			session.dispose();
+			this.sessions.delete(sessionId);
+			this.clearKillTimer(sessionId);
+			session = undefined;
+		}
+
+		// If session exists but is dead, dispose it and create a new one
+		if (session && !session.isAlive) {
+			session.dispose();
+			this.sessions.delete(sessionId);
+			session = undefined;
+		}
+
+		if (!session) {
+			// Create new session
+			session = createSession(request);
+
+			// Set up exit handler
+			session.onExit((id, exitCode, signal) => {
+				this.handleSessionExit(id, exitCode, signal);
+			});
+
+			// Spawn PTY
+			session.spawn({
+				cwd: request.cwd || process.env.HOME || "/",
+				cols: request.cols,
+				rows: request.rows,
+				env: request.env,
+			});
+
+			// Run initial commands if provided (after PTY is ready)
+			if (request.initialCommands && request.initialCommands.length > 0) {
+				const initialCommands = request.initialCommands;
+				// Wait for PTY to be ready, then run commands
+				session.waitForReady().then(() => {
+					// Double-check session is still alive after await
+					if (session?.isAlive) {
+						try {
+							const cmdString = `${initialCommands.join(" && ")}\n`;
+							session.write(cmdString);
+						} catch (error) {
+							// Log but don't crash - initialCommands are best-effort
+							console.error(
+								`[TerminalHost] Failed to run initial commands for ${sessionId}:`,
+								error,
+							);
+						}
+					}
+				});
+			}
+
+			this.sessions.set(sessionId, session);
+			isNew = true;
+		} else {
+			// Attaching to existing live session - resize to requested dimensions
+			// This ensures the snapshot reflects the client's current terminal size
+			// Note: Resize can fail if PTY is in a bad state (e.g., EBADF)
+			// We catch and ignore these errors since the session may still be usable
+			try {
+				session.resize(request.cols, request.rows);
+			} catch {
+				// Ignore resize failures - session may still be attachable
+			}
+		}
+
+		// Attach client to session (async to ensure pending writes are flushed)
+		const snapshot = await session.attach(socket);
+
+		return {
+			isNew,
+			snapshot,
+			wasRecovered: !isNew && session.isAlive,
+		};
+	}
+
+	/**
+	 * Write data to a terminal session.
+	 * Throws if session is not found or is terminating.
+	 */
+	write(request: WriteRequest): EmptyResponse {
+		const session = this.getActiveSession(request.sessionId);
+		session.write(request.data);
+		return { success: true };
+	}
+
+	/**
+	 * Resize a terminal session.
+	 * Throws if session is not found or is terminating.
+	 */
+	resize(request: ResizeRequest): EmptyResponse {
+		const session = this.getActiveSession(request.sessionId);
+		session.resize(request.cols, request.rows);
+		return { success: true };
+	}
+
+	/**
+	 * Detach a client from a session
+	 */
+	detach(socket: Socket, request: DetachRequest): EmptyResponse {
+		const session = this.sessions.get(request.sessionId);
+		if (session) {
+			session.detach(socket);
+			// Clean up dead sessions when last client detaches
+			if (!session.isAlive && session.clientCount === 0) {
+				session.dispose();
+				this.sessions.delete(request.sessionId);
+			}
+		}
+		return { success: true };
+	}
+
+	/**
+	 * Kill a terminal session.
+	 * The session is marked as terminating immediately (non-attachable).
+	 * A fail-safe timer ensures cleanup even if the PTY never exits.
+	 */
+	kill(request: KillRequest): EmptyResponse {
+		const { sessionId } = request;
+		const session = this.sessions.get(sessionId);
+
+		if (!session) {
+			return { success: true };
+		}
+
+		session.kill();
+
+		// Set up fail-safe timer to force-dispose if exit never fires.
+		// This prevents zombie sessions if the PTY process hangs.
+		if (!this.killTimers.has(sessionId)) {
+			const timer = setTimeout(() => {
+				const s = this.sessions.get(sessionId);
+				if (s?.isTerminating) {
+					console.warn(
+						`[TerminalHost] Force disposing stuck session ${sessionId} after ${KILL_TIMEOUT_MS}ms`,
+					);
+					s.dispose();
+					this.sessions.delete(sessionId);
+				}
+				this.killTimers.delete(sessionId);
+			}, KILL_TIMEOUT_MS);
+			this.killTimers.set(sessionId, timer);
+		}
+
+		return { success: true };
+	}
+
+	/**
+	 * Kill all terminal sessions
+	 */
+	killAll(_request: KillAllRequest): EmptyResponse {
+		for (const session of this.sessions.values()) {
+			session.kill();
+		}
+		// Sessions will be removed on exit events
+		return { success: true };
+	}
+
+	/**
+	 * List all sessions.
+	 * Note: isAlive reports isAttachable (alive AND not terminating) to prevent
+	 * race conditions where killByWorkspaceId sees a session as alive while
+	 * it's actually in the process of being killed.
+	 */
+	listSessions(): ListSessionsResponse {
+		const sessions = Array.from(this.sessions.values()).map((session) => ({
+			sessionId: session.sessionId,
+			workspaceId: session.workspaceId,
+			paneId: session.paneId,
+			isAlive: session.isAttachable, // Use isAttachable to prevent kill/attach races
+			attachedClients: session.clientCount,
+		}));
+
+		return { sessions };
+	}
+
+	/**
+	 * Clear scrollback for a session.
+	 * Throws if session is not found or is terminating.
+	 */
+	clearScrollback(request: ClearScrollbackRequest): EmptyResponse {
+		const session = this.getActiveSession(request.sessionId);
+		session.clearScrollback();
+		return { success: true };
+	}
+
+	/**
+	 * Detach a socket from all sessions it's attached to
+	 * Called when a client connection closes
+	 */
+	detachFromAllSessions(socket: Socket): void {
+		for (const [sessionId, session] of this.sessions.entries()) {
+			session.detach(socket);
+			// Clean up dead sessions when last client detaches
+			if (!session.isAlive && session.clientCount === 0) {
+				session.dispose();
+				this.sessions.delete(sessionId);
+			}
+		}
+	}
+
+	/**
+	 * Clean up all sessions on shutdown
+	 */
+	dispose(): void {
+		// Clear all kill timers
+		for (const timer of this.killTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.killTimers.clear();
+
+		// Dispose all sessions
+		for (const session of this.sessions.values()) {
+			session.dispose();
+		}
+		this.sessions.clear();
+	}
+
+	/**
+	 * Get an active (attachable) session by ID.
+	 * Throws if session doesn't exist or is terminating.
+	 * Use this for mutating operations (write, resize, clearScrollback).
+	 */
+	private getActiveSession(sessionId: string): Session {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			throw new Error(`Session not found: ${sessionId}`);
+		}
+		if (!session.isAttachable) {
+			throw new Error(`Session not attachable: ${sessionId}`);
+		}
+		return session;
+	}
+
+	/**
+	 * Handle session exit
+	 */
+	private handleSessionExit(
+		sessionId: string,
+		_exitCode: number,
+		_signal?: number,
+	): void {
+		// Clear the kill timer since session exited normally
+		this.clearKillTimer(sessionId);
+
+		// Keep session around for a bit so clients can see exit status
+		// Then clean up (reschedule if clients still attached)
+		this.scheduleSessionCleanup(sessionId);
+	}
+
+	/**
+	 * Clear the kill timeout for a session
+	 */
+	private clearKillTimer(sessionId: string): void {
+		const timer = this.killTimers.get(sessionId);
+		if (timer) {
+			clearTimeout(timer);
+			this.killTimers.delete(sessionId);
+		}
+	}
+
+	/**
+	 * Schedule cleanup of a dead session
+	 * Reschedules if clients are still attached
+	 */
+	private scheduleSessionCleanup(sessionId: string): void {
+		setTimeout(() => {
+			const session = this.sessions.get(sessionId);
+			if (!session || session.isAlive) {
+				// Session was recreated or is alive, nothing to clean up
+				return;
+			}
+
+			if (session.clientCount === 0) {
+				// No clients attached, safe to clean up
+				session.dispose();
+				this.sessions.delete(sessionId);
+			} else {
+				// Clients still attached, reschedule cleanup
+				// They'll see the exit status and can restart
+				this.scheduleSessionCleanup(sessionId);
+			}
+		}, 5000);
+	}
+}
diff --git a/apps/desktop/src/main/windows/main.ts b/apps/desktop/src/main/windows/main.ts
index fb29400b1a9..ba393a6208a 100644
--- a/apps/desktop/src/main/windows/main.ts
+++ b/apps/desktop/src/main/windows/main.ts
@@ -13,11 +13,11 @@ import { appState } from "../lib/app-state";
 import { createApplicationMenu, registerMenuHotkeyUpdates } from "../lib/menu";
 import { playNotificationSound } from "../lib/notification-sound";
 import {
-	type AgentCompleteEvent,
+	type AgentLifecycleEvent,
 	notificationsApp,
 	notificationsEmitter,
 } from "../lib/notifications/server";
-import { terminalManager } from "../lib/terminal";
+import { getActiveTerminalManager } from "../lib/terminal";
 
 // Singleton IPC handler to prevent duplicate handlers on window reopen (macOS)
 let ipcHandler: ReturnType<typeof createIPCHandler> | null = null;
@@ -78,10 +78,13 @@ export async function MainWindow() {
 		},
 	);
 
-	// Handle agent completion notifications
+	// Handle agent lifecycle notifications (Stop = completion, PermissionRequest = needs input)
 	notificationsEmitter.on(
-		NOTIFICATION_EVENTS.AGENT_COMPLETE,
-		(event: AgentCompleteEvent) => {
+		NOTIFICATION_EVENTS.AGENT_LIFECYCLE,
+		(event: AgentLifecycleEvent) => {
+			// Only notify on Stop (completion) and PermissionRequest - not on Start
+			if (event.eventType === "Start") return;
+
 			if (Notification.isSupported()) {
 				const isPermissionRequest = event.eventType === "PermissionRequest";
 
@@ -164,7 +167,7 @@ export async function MainWindow() {
 		server.close();
 		notificationsEmitter.removeAllListeners();
 		// Remove terminal listeners to prevent duplicates when window reopens on macOS
-		terminalManager.detachAllListeners();
+		getActiveTerminalManager().detachAllListeners();
 		// Detach window from IPC handler (handler stays alive for window reopen)
 		ipcHandler?.detachWindow(window);
 		// Clear current window reference
diff --git a/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsContent.tsx b/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsContent.tsx
index 2af699cd289..e8cdd79e3d9 100644
--- a/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsContent.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsContent.tsx
@@ -6,6 +6,7 @@ import { KeyboardShortcutsSettings } from "./KeyboardShortcutsSettings";
 import { PresetsSettings } from "./PresetsSettings";
 import { ProjectSettings } from "./ProjectSettings";
 import { RingtonesSettings } from "./RingtonesSettings";
+import { TerminalSettings } from "./TerminalSettings";
 import { WorkspaceSettings } from "./WorkspaceSettings";
 
 interface SettingsContentProps {
@@ -22,6 +23,7 @@ export function SettingsContent({ activeSection }: SettingsContentProps) {
 			{activeSection === "ringtones" && <RingtonesSettings />}
 			{activeSection === "keyboard" && <KeyboardShortcutsSettings />}
 			{activeSection === "presets" && <PresetsSettings />}
+			{activeSection === "terminal" && <TerminalSettings />}
 			{activeSection === "behavior" && <BehaviorSettings />}
 		</div>
 	);
diff --git a/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsSidebar/GeneralSettings.tsx b/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsSidebar/GeneralSettings.tsx
index 7803fa3b11f..eea13a7db7c 100644
--- a/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsSidebar/GeneralSettings.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/SettingsView/SettingsSidebar/GeneralSettings.tsx
@@ -4,6 +4,7 @@ import {
 	HiOutlineBell,
 	HiOutlineCog6Tooth,
 	HiOutlineCommandLine,
+	HiOutlineComputerDesktop,
 	HiOutlinePaintBrush,
 	HiOutlineUser,
 } from "react-icons/hi2";
@@ -44,6 +45,11 @@ const GENERAL_SECTIONS: {
 		label: "Presets",
 		icon: <HiOutlineCog6Tooth className="h-4 w-4" />,
 	},
+	{
+		id: "terminal",
+		label: "Terminal",
+		icon: <HiOutlineComputerDesktop className="h-4 w-4" />,
+	},
 	{
 		id: "behavior",
 		label: "Behavior",
diff --git a/apps/desktop/src/renderer/screens/main/components/SettingsView/TerminalSettings.tsx b/apps/desktop/src/renderer/screens/main/components/SettingsView/TerminalSettings.tsx
new file mode 100644
index 00000000000..4e4e6cafe78
--- /dev/null
+++ b/apps/desktop/src/renderer/screens/main/components/SettingsView/TerminalSettings.tsx
@@ -0,0 +1,80 @@
+import { Label } from "@superset/ui/label";
+import { Switch } from "@superset/ui/switch";
+import { trpc } from "renderer/lib/trpc";
+
+export function TerminalSettings() {
+	const utils = trpc.useUtils();
+	const { data: terminalPersistence, isLoading } =
+		trpc.settings.getTerminalPersistence.useQuery();
+	const setTerminalPersistence =
+		trpc.settings.setTerminalPersistence.useMutation({
+			onMutate: async ({ enabled }) => {
+				// Cancel outgoing fetches
+				await utils.settings.getTerminalPersistence.cancel();
+				// Snapshot previous value
+				const previous = utils.settings.getTerminalPersistence.getData();
+				// Optimistically update
+				utils.settings.getTerminalPersistence.setData(undefined, enabled);
+				return { previous };
+			},
+			onError: (_err, _vars, context) => {
+				// Rollback on error
+				if (context?.previous !== undefined) {
+					utils.settings.getTerminalPersistence.setData(
+						undefined,
+						context.previous,
+					);
+				}
+			},
+			onSettled: () => {
+				// Refetch to ensure sync with server
+				utils.settings.getTerminalPersistence.invalidate();
+			},
+		});
+
+	const handleToggle = (enabled: boolean) => {
+		setTerminalPersistence.mutate({ enabled });
+	};
+
+	return (
+		<div className="p-6 max-w-4xl w-full">
+			<div className="mb-8">
+				<h2 className="text-xl font-semibold">Terminal</h2>
+				<p className="text-sm text-muted-foreground mt-1">
+					Configure terminal behavior and persistence
+				</p>
+			</div>
+
+			<div className="space-y-6">
+				<div className="flex items-center justify-between">
+					<div className="space-y-0.5">
+						<Label
+							htmlFor="terminal-persistence"
+							className="text-sm font-medium"
+						>
+							Terminal persistence
+						</Label>
+						<p className="text-xs text-muted-foreground">
+							Keep terminal sessions alive across app restarts and workspace
+							switches. TUI apps like Claude Code will resume exactly where you
+							left off.
+						</p>
+						<p className="text-xs text-muted-foreground/70 mt-1">
+							May use more memory with many terminals open. Disable if you
+							notice performance issues.
+						</p>
+						<p className="text-xs text-muted-foreground/70 mt-1">
+							Requires app restart to take effect.
+						</p>
+					</div>
+					<Switch
+						id="terminal-persistence"
+						checked={terminalPersistence ?? false}
+						onCheckedChange={handleToggle}
+						disabled={isLoading || setTerminalPersistence.isPending}
+					/>
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceTabs/WorkspaceItem.tsx b/apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceTabs/WorkspaceItem.tsx
index b98e36c98c2..e8980dd352d 100644
--- a/apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceTabs/WorkspaceItem.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceTabs/WorkspaceItem.tsx
@@ -56,8 +56,8 @@ export function WorkspaceItem({
 	const closeSettings = useCloseSettings();
 	const tabs = useTabsStore((s) => s.tabs);
 	const panes = useTabsStore((s) => s.panes);
-	const clearWorkspaceAttention = useTabsStore(
-		(s) => s.clearWorkspaceAttention,
+	const clearWorkspaceAttentionStatus = useTabsStore(
+		(s) => s.clearWorkspaceAttentionStatus,
 	);
 	const rename = useWorkspaceRename(id, title);
 
@@ -65,17 +65,30 @@ export function WorkspaceItem({
 	const { showDeleteDialog, setShowDeleteDialog, handleDeleteClick } =
 		useWorkspaceDeleteHandler();
 
-	// Check if any pane in tabs belonging to this workspace needs attention (agent notifications)
+	// Derive aggregate status from panes in this workspace
+	// Priority: permission (red) > working (amber) > review (green)
 	const workspaceTabs = tabs.filter((t) => t.workspaceId === id);
 	const workspacePaneIds = new Set(
 		workspaceTabs.flatMap((t) => extractPaneIdsFromLayout(t.layout)),
 	);
-	const hasPaneAttention = Object.values(panes)
-		.filter((p) => workspacePaneIds.has(p.id))
-		.some((p) => p.needsAttention);
+	const workspacePanes = Object.values(panes).filter((p) =>
+		workspacePaneIds.has(p.id),
+	);
+
+	const hasPermission = workspacePanes.some((p) => p.status === "permission");
+	const hasWorking = workspacePanes.some((p) => p.status === "working");
+	const hasReview = workspacePanes.some((p) => p.status === "review");
 
-	// Show indicator if workspace is manually marked as unread OR has pane-level attention
-	const needsAttention = isUnread || hasPaneAttention;
+	// Aggregate status for the workspace (priority order)
+	const aggregateStatus = hasPermission
+		? "permission"
+		: hasWorking
+			? "working"
+			: hasReview
+				? "review"
+				: isUnread
+					? "review" // isUnread maps to review color
+					: null;
 
 	const [{ isDragging }, drag] = useDrag(
 		() => ({
@@ -128,7 +141,7 @@ export function WorkspaceItem({
 							if (!rename.isRenaming) {
 								closeSettings();
 								setActive.mutate({ id });
-								clearWorkspaceAttention(id);
+								clearWorkspaceAttentionStatus(id);
 							}
 						}}
 						onDoubleClick={isBranchWorkspace ? undefined : rename.startRename}
@@ -208,10 +221,23 @@ export function WorkspaceItem({
 								>
 									{title}
 								</span>
-								{needsAttention && (
+								{aggregateStatus && (
 									<span className="relative flex size-2 shrink-0">
-										<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
-										<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+										{aggregateStatus === "permission" && (
+											<>
+												<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
+												<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+											</>
+										)}
+										{aggregateStatus === "working" && (
+											<>
+												<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-amber-400 opacity-75" />
+												<span className="relative inline-flex size-2 rounded-full bg-amber-500" />
+											</>
+										)}
+										{aggregateStatus === "review" && (
+											<span className="relative inline-flex size-2 rounded-full bg-green-500" />
+										)}
 									</span>
 								)}
 							</>
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/WorkspaceListItem/WorkspaceListItem.tsx b/apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/WorkspaceListItem/WorkspaceListItem.tsx
index 9a1ca16b45d..804bbf7e098 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/WorkspaceListItem/WorkspaceListItem.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/WorkspaceListItem/WorkspaceListItem.tsx
@@ -73,8 +73,8 @@ export function WorkspaceListItem({
 	const rename = useWorkspaceRename(id, name);
 	const tabs = useTabsStore((s) => s.tabs);
 	const panes = useTabsStore((s) => s.panes);
-	const clearWorkspaceAttention = useTabsStore(
-		(s) => s.clearWorkspaceAttention,
+	const clearWorkspaceAttentionStatus = useTabsStore(
+		(s) => s.clearWorkspaceAttentionStatus,
 	);
 	const utils = trpc.useUtils();
 	const openInFinder = trpc.external.openInFinder.useMutation();
@@ -97,22 +97,35 @@ export function WorkspaceListItem({
 		},
 	);
 
-	// Check if any pane in tabs belonging to this workspace needs attention (agent notifications)
+	// Derive aggregate status from panes in this workspace
+	// Priority: permission (red) > working (amber) > review (green)
 	const workspaceTabs = tabs.filter((t) => t.workspaceId === id);
 	const workspacePaneIds = new Set(
 		workspaceTabs.flatMap((t) => extractPaneIdsFromLayout(t.layout)),
 	);
-	const hasPaneAttention = Object.values(panes)
-		.filter((p) => workspacePaneIds.has(p.id))
-		.some((p) => p.needsAttention);
+	const workspacePanes = Object.values(panes).filter((p) =>
+		workspacePaneIds.has(p.id),
+	);
+
+	const hasPermission = workspacePanes.some((p) => p.status === "permission");
+	const hasWorking = workspacePanes.some((p) => p.status === "working");
+	const hasReview = workspacePanes.some((p) => p.status === "review");
 
-	// Show indicator if workspace is manually marked as unread OR has pane-level attention
-	const needsAttention = isUnread || hasPaneAttention;
+	// Aggregate status for the workspace (priority order)
+	const aggregateStatus = hasPermission
+		? "permission"
+		: hasWorking
+			? "working"
+			: hasReview
+				? "review"
+				: isUnread
+					? "review" // isUnread maps to review color
+					: null;
 
 	const handleClick = () => {
 		if (!rename.isRenaming) {
 			setActiveWorkspace.mutate({ id });
-			clearWorkspaceAttention(id);
+			clearWorkspaceAttentionStatus(id);
 		}
 	};
 
@@ -214,10 +227,23 @@ export function WorkspaceListItem({
 							{pr && (
 								<WorkspaceStatusBadge state={pr.state} prNumber={pr.number} />
 							)}
-							{needsAttention && (
+							{aggregateStatus && (
 								<span className="relative flex size-2 shrink-0">
-									<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
-									<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+									{aggregateStatus === "permission" && (
+										<>
+											<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
+											<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+										</>
+									)}
+									{aggregateStatus === "working" && (
+										<>
+											<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-amber-400 opacity-75" />
+											<span className="relative inline-flex size-2 rounded-full bg-amber-500" />
+										</>
+									)}
+									{aggregateStatus === "review" && (
+										<span className="relative inline-flex size-2 rounded-full bg-green-500" />
+									)}
 								</span>
 							)}
 						</div>
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/GroupStrip/GroupStrip.tsx b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/GroupStrip/GroupStrip.tsx
index 77790ae7b88..4159ed7bb7f 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/GroupStrip/GroupStrip.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/GroupStrip/GroupStrip.tsx
@@ -5,13 +5,13 @@ import { useMemo } from "react";
 import { HiMiniPlus, HiMiniXMark } from "react-icons/hi2";
 import { trpc } from "renderer/lib/trpc";
 import { useTabsStore } from "renderer/stores/tabs/store";
-import type { Tab } from "renderer/stores/tabs/types";
+import type { PaneStatus, Tab } from "renderer/stores/tabs/types";
 import { getTabDisplayName } from "renderer/stores/tabs/utils";
 
 interface GroupItemProps {
 	tab: Tab;
 	isActive: boolean;
-	needsAttention: boolean;
+	status: PaneStatus | null;
 	onSelect: () => void;
 	onClose: () => void;
 }
@@ -19,7 +19,7 @@ interface GroupItemProps {
 function GroupItem({
 	tab,
 	isActive,
-	needsAttention,
+	status,
 	onSelect,
 	onClose,
 }: GroupItemProps) {
@@ -42,10 +42,23 @@ function GroupItem({
 						<span className="text-sm whitespace-nowrap overflow-hidden flex-1 text-left">
 							{displayName}
 						</span>
-						{needsAttention && (
+						{status && status !== "idle" && (
 							<span className="relative flex size-2 shrink-0">
-								<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
-								<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+								{status === "permission" && (
+									<>
+										<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
+										<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+									</>
+								)}
+								{status === "working" && (
+									<>
+										<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-amber-400 opacity-75" />
+										<span className="relative inline-flex size-2 rounded-full bg-amber-500" />
+									</>
+								)}
+								{status === "review" && (
+									<span className="relative inline-flex size-2 rounded-full bg-green-500" />
+								)}
 							</span>
 						)}
 					</button>
@@ -104,12 +117,24 @@ export function GroupStrip() {
 		? activeTabIds[activeWorkspaceId]
 		: null;
 
-	// Check which tabs have panes that need attention
-	const tabsWithAttention = useMemo(() => {
-		const result = new Set<string>();
+	// Compute aggregate status per tab (priority: permission > working > review)
+	const tabStatusMap = useMemo(() => {
+		const result = new Map<string, PaneStatus>();
 		for (const pane of Object.values(panes)) {
-			if (pane.needsAttention) {
-				result.add(pane.tabId);
+			if (!pane.status || pane.status === "idle") continue;
+
+			const currentStatus = result.get(pane.tabId);
+			// Priority: permission > working > review
+			if (pane.status === "permission") {
+				result.set(pane.tabId, "permission");
+			} else if (pane.status === "working" && currentStatus !== "permission") {
+				result.set(pane.tabId, "working");
+			} else if (
+				pane.status === "review" &&
+				currentStatus !== "permission" &&
+				currentStatus !== "working"
+			) {
+				result.set(pane.tabId, "review");
 			}
 		}
 		return result;
@@ -144,7 +169,7 @@ export function GroupStrip() {
 							<GroupItem
 								tab={tab}
 								isActive={tab.id === activeTabId}
-								needsAttention={tabsWithAttention.has(tab.id)}
+								status={tabStatusMap.get(tab.id) ?? null}
 								onSelect={() => handleSelectGroup(tab.id)}
 								onClose={() => handleCloseGroup(tab.id)}
 							/>
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/Terminal.tsx b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/Terminal.tsx
index 2c73582c9af..91a6fb34247 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/Terminal.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/Terminal.tsx
@@ -1,6 +1,7 @@
+import { toast } from "@superset/ui/sonner";
 import type { FitAddon } from "@xterm/addon-fit";
 import type { SearchAddon } from "@xterm/addon-search";
-import type { Terminal as XTerm } from "@xterm/xterm";
+import type { IDisposable, Terminal as XTerm } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
 import debounce from "lodash/debounce";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -19,12 +20,49 @@ import {
 	setupKeyboardHandler,
 	setupPasteHandler,
 	setupResizeHandlers,
+	type TerminalRendererRef,
 } from "./helpers";
+import { useTerminalConnection } from "./hooks";
 import { parseCwd } from "./parseCwd";
 import { TerminalSearch } from "./TerminalSearch";
 import type { TerminalProps, TerminalStreamEvent } from "./types";
 import { shellEscapePaths } from "./utils";
 
+const FIRST_RENDER_RESTORE_FALLBACK_MS = 250;
+
+// Module-level map to track pending detach timeouts.
+// This survives React StrictMode's unmount/remount cycle, allowing us to
+// cancel a pending detach if the component immediately remounts.
+const pendingDetaches = new Map<string, NodeJS.Timeout>();
+
+type CreateOrAttachResult = {
+	wasRecovered: boolean;
+	isNew: boolean;
+	scrollback: string;
+	snapshot?: {
+		snapshotAnsi: string;
+		rehydrateSequences: string;
+		cwd: string | null;
+		modes: Record<string, boolean>;
+		cols: number;
+		rows: number;
+		scrollbackLines: number;
+		debug?: {
+			xtermBufferType: string;
+			hasAltScreenEntry: boolean;
+			altBuffer?: {
+				lines: number;
+				nonEmptyLines: number;
+				totalChars: number;
+				cursorX: number;
+				cursorY: number;
+				sampleLines: string[];
+			};
+			normalBufferLines: number;
+		};
+	};
+};
+
 export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 	const paneId = tabId;
 	const panes = useTabsStore((s) => s.panes);
@@ -37,10 +75,10 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 	const xtermRef = useRef<XTerm | null>(null);
 	const fitAddonRef = useRef<FitAddon | null>(null);
 	const searchAddonRef = useRef<SearchAddon | null>(null);
+	const rendererRef = useRef<TerminalRendererRef | null>(null);
 	const isExitedRef = useRef(false);
 	const pendingEventsRef = useRef<TerminalStreamEvent[]>([]);
 	const commandBufferRef = useRef("");
-	const [subscriptionEnabled, setSubscriptionEnabled] = useState(false);
 	const [isSearchOpen, setIsSearchOpen] = useState(false);
 	const [terminalCwd, setTerminalCwd] = useState<string | null>(null);
 	const [cwdConfirmed, setCwdConfirmed] = useState(false);
@@ -51,11 +89,42 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 	const addFileViewerPane = useTabsStore((s) => s.addFileViewerPane);
 	const terminalTheme = useTerminalTheme();
 
+	// Terminal connection state and mutations (extracted to hook for cleaner code)
+	const {
+		connectionError,
+		setConnectionError,
+		workspaceCwd,
+		refs: {
+			createOrAttach: createOrAttachRef,
+			write: writeRef,
+			resize: resizeRef,
+			detach: detachRef,
+			clearScrollback: clearScrollbackRef,
+		},
+	} = useTerminalConnection({ workspaceId });
+
 	// Ref for initial theme to avoid recreating terminal on theme change
 	const initialThemeRef = useRef(terminalTheme);
 
 	const isFocused = pane?.tabId ? focusedPaneIds[pane.tabId] === paneId : false;
 
+	// Gate streaming until initial state restoration is applied to avoid interleaving output.
+	const isStreamReadyRef = useRef(false);
+
+	// Gate restoration until xterm has rendered at least once (renderer/viewport ready).
+	const didFirstRenderRef = useRef(false);
+	const pendingInitialStateRef = useRef<CreateOrAttachResult | null>(null);
+	const renderDisposableRef = useRef<IDisposable | null>(null);
+	const restoreSequenceRef = useRef(0);
+
+	// Track alternate screen mode ourselves (xterm.buffer.active.type is unreliable after HMR/recovery)
+	// Updated from: snapshot.modes.alternateScreen on restore, escape sequences in stream
+	const isAlternateScreenRef = useRef(false);
+	// Track bracketed paste mode so large pastes can preserve a single bracketed-paste envelope.
+	const isBracketedPasteRef = useRef(false);
+	// Track mode toggles across chunk boundaries (escape sequences can span stream frames).
+	const modeScanBufferRef = useRef("");
+
 	// Refs avoid effect re-runs when these values change
 	const isFocusedRef = useRef(isFocused);
 	isFocusedRef.current = isFocused;
@@ -67,8 +136,10 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 	paneInitialCwdRef.current = paneInitialCwd;
 	clearPaneInitialDataRef.current = clearPaneInitialData;
 
-	const { data: workspaceCwd } =
-		trpc.terminal.getWorkspaceCwd.useQuery(workspaceId);
+	// Use ref for workspaceCwd to avoid terminal recreation when query loads
+	// (changing from undefined→string triggers useEffect, causing xterm errors)
+	const workspaceCwdRef = useRef(workspaceCwd);
+	workspaceCwdRef.current = workspaceCwd;
 
 	// Query terminal link behavior setting
 	const { data: terminalLinkBehavior } =
@@ -153,23 +224,6 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 	const updateCwdRef = useRef(updateCwdFromData);
 	updateCwdRef.current = updateCwdFromData;
 
-	const createOrAttachMutation = trpc.terminal.createOrAttach.useMutation();
-	const writeMutation = trpc.terminal.write.useMutation();
-	const resizeMutation = trpc.terminal.resize.useMutation();
-	const detachMutation = trpc.terminal.detach.useMutation();
-	const clearScrollbackMutation = trpc.terminal.clearScrollback.useMutation();
-
-	const createOrAttachRef = useRef(createOrAttachMutation.mutate);
-	const writeRef = useRef(writeMutation.mutate);
-	const resizeRef = useRef(resizeMutation.mutate);
-	const detachRef = useRef(detachMutation.mutate);
-	const clearScrollbackRef = useRef(clearScrollbackMutation.mutate);
-	createOrAttachRef.current = createOrAttachMutation.mutate;
-	writeRef.current = writeMutation.mutate;
-	resizeRef.current = resizeMutation.mutate;
-	detachRef.current = detachMutation.mutate;
-	clearScrollbackRef.current = clearScrollbackMutation.mutate;
-
 	const registerClearCallbackRef = useRef(
 		useTerminalCallbacksStore.getState().registerClearCallback,
 	);
@@ -189,23 +243,362 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 		}, 100),
 	);
 
+	const updateModesFromData = useCallback((data: string) => {
+		// Escape sequences can be split across streamed frames, so scan using a small carry buffer.
+		const combined = modeScanBufferRef.current + data;
+
+		const enterAltIndex = Math.max(
+			combined.lastIndexOf("\x1b[?1049h"),
+			combined.lastIndexOf("\x1b[?47h"),
+		);
+		const exitAltIndex = Math.max(
+			combined.lastIndexOf("\x1b[?1049l"),
+			combined.lastIndexOf("\x1b[?47l"),
+		);
+		if (enterAltIndex !== -1 || exitAltIndex !== -1) {
+			isAlternateScreenRef.current = enterAltIndex > exitAltIndex;
+		}
+
+		const enableBracketedIndex = combined.lastIndexOf("\x1b[?2004h");
+		const disableBracketedIndex = combined.lastIndexOf("\x1b[?2004l");
+		if (enableBracketedIndex !== -1 || disableBracketedIndex !== -1) {
+			isBracketedPasteRef.current =
+				enableBracketedIndex > disableBracketedIndex;
+		}
+
+		// Keep a small tail in case the next chunk starts mid-sequence.
+		modeScanBufferRef.current = combined.slice(-32);
+	}, []);
+
+	const updateModesFromDataRef = useRef(updateModesFromData);
+	updateModesFromDataRef.current = updateModesFromData;
+
+	const flushPendingEvents = useCallback(() => {
+		const xterm = xtermRef.current;
+		if (!xterm) return;
+		if (pendingEventsRef.current.length === 0) return;
+
+		const events = pendingEventsRef.current.splice(
+			0,
+			pendingEventsRef.current.length,
+		);
+
+		for (const event of events) {
+			if (event.type === "data") {
+				updateModesFromDataRef.current(event.data);
+				xterm.write(event.data);
+				updateCwdRef.current(event.data);
+			} else if (event.type === "exit") {
+				isExitedRef.current = true;
+				isStreamReadyRef.current = false;
+				xterm.writeln(`\r\n\r\n[Process exited with code ${event.exitCode}]`);
+				xterm.writeln("[Press any key to restart]");
+			} else if (event.type === "disconnect") {
+				setConnectionError(
+					event.reason || "Connection to terminal daemon lost",
+				);
+			} else if (event.type === "error") {
+				const message = event.code
+					? `${event.code}: ${event.error}`
+					: event.error;
+				console.warn("[Terminal] stream error:", message);
+
+				toast.error("Terminal error", {
+					description: message,
+				});
+
+				// Don't block interaction for non-fatal issues like a paste drop or a
+				// transient write failure (we keep the session alive).
+				if (
+					event.code === "WRITE_QUEUE_FULL" ||
+					event.code === "WRITE_FAILED"
+				) {
+					xterm.writeln(`\r\n[Terminal] ${message}`);
+				} else {
+					setConnectionError(message);
+				}
+			}
+		}
+	}, [setConnectionError]);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: refs (resizeRef, updateCwdRef, rendererRef) used intentionally to read latest values without recreating callback
+	const maybeApplyInitialState = useCallback(() => {
+		if (!didFirstRenderRef.current) return;
+		const result = pendingInitialStateRef.current;
+		if (!result) return;
+
+		const xterm = xtermRef.current;
+		const fitAddon = fitAddonRef.current;
+		if (!xterm || !fitAddon) return;
+
+		// Clear before applying to prevent double-apply on concurrent triggers.
+		pendingInitialStateRef.current = null;
+		const restoreSequence = ++restoreSequenceRef.current;
+
+		try {
+			// Canonical initial content: prefer snapshot (daemon mode) over scrollback (non-daemon)
+			// In daemon mode, scrollback is empty to avoid duplicating the payload over IPC.
+			const initialAnsi = result.snapshot?.snapshotAnsi ?? result.scrollback;
+
+			// Track alternate screen mode from snapshot for our own reference
+			// (xterm.buffer.active.type is unreliable after HMR/recovery)
+			isAlternateScreenRef.current = !!result.snapshot?.modes.alternateScreen;
+			isBracketedPasteRef.current = !!result.snapshot?.modes.bracketedPaste;
+			modeScanBufferRef.current = "";
+
+			// Fallback: parse initialAnsi for escape sequences when snapshot.modes is unavailable.
+			// This handles non-daemon mode and edge cases where daemon didn't track the mode.
+			if (initialAnsi && result.snapshot?.modes === undefined) {
+				// Use lastIndexOf to find the final state - handles multiple enter/exit cycles
+				// (e.g., user opened vim, closed it, opened it again)
+				const enterAltIndex = Math.max(
+					initialAnsi.lastIndexOf("\x1b[?1049h"),
+					initialAnsi.lastIndexOf("\x1b[?47h"),
+				);
+				const exitAltIndex = Math.max(
+					initialAnsi.lastIndexOf("\x1b[?1049l"),
+					initialAnsi.lastIndexOf("\x1b[?47l"),
+				);
+				if (enterAltIndex !== -1 || exitAltIndex !== -1) {
+					isAlternateScreenRef.current = enterAltIndex > exitAltIndex;
+				}
+
+				// Bracketed paste mode can toggle during a session - use the last seen state.
+				const bracketEnableIndex = initialAnsi.lastIndexOf("\x1b[?2004h");
+				const bracketDisableIndex = initialAnsi.lastIndexOf("\x1b[?2004l");
+				if (bracketEnableIndex !== -1 || bracketDisableIndex !== -1) {
+					isBracketedPasteRef.current =
+						bracketEnableIndex > bracketDisableIndex;
+				}
+			}
+
+			// Apply rehydration sequences to restore other terminal modes
+			// (app cursor mode, bracketed paste, mouse tracking, etc.)
+			if (result.snapshot?.rehydrateSequences) {
+				xterm.write(result.snapshot.rehydrateSequences);
+			}
+
+			// Resize xterm to match snapshot dimensions before applying content.
+			// The snapshot's cursor positioning assumes specific cols/rows.
+			const snapshotCols = result.snapshot?.cols;
+			const snapshotRows = result.snapshot?.rows;
+			if (
+				snapshotCols &&
+				snapshotRows &&
+				(xterm.cols !== snapshotCols || xterm.rows !== snapshotRows)
+			) {
+				xterm.resize(snapshotCols, snapshotRows);
+			}
+
+			const isAltScreenReattach =
+				!result.isNew && result.snapshot?.modes.alternateScreen;
+
+			// For alt-screen (TUI) sessions, the serialized snapshot often renders
+			// incorrectly because styled spaces and positioning get lost. Instead of
+			// writing broken snapshot, enter alt-screen and trigger SIGWINCH so the
+			// TUI redraws itself via the live stream.
+			// NOTE: This is primarily a fallback path for app restart recovery.
+			// During normal workspace/tab switching with persistence enabled,
+			// terminals stay mounted and this code path is not triggered.
+			if (isAltScreenReattach) {
+				// Enter alt-screen mode and WAIT for xterm to process it before proceeding.
+				// xterm.write() is async - if we trigger SIGWINCH before alt-screen is entered,
+				// the TUI receives SIGWINCH in normal mode, ignores it, then xterm switches
+				// buffers and we get a white screen.
+				xterm.write("\x1b[?1049h", () => {
+					// Apply rehydration sequences for other modes (bracketed paste, etc.)
+					if (result.snapshot?.rehydrateSequences) {
+						// Filter out alt-screen sequences since we already entered
+						const ESC = "\x1b";
+						const filteredRehydrate = result.snapshot.rehydrateSequences
+							.split(`${ESC}[?1049h`)
+							.join("")
+							.split(`${ESC}[?47h`)
+							.join("");
+						if (filteredRehydrate) {
+							xterm.write(filteredRehydrate);
+						}
+					}
+
+					// NOW safe to enable streaming and flush pending events
+					isStreamReadyRef.current = true;
+					flushPendingEvents();
+
+					// Fit xterm to container and trigger SIGWINCH
+					requestAnimationFrame(() => {
+						if (xtermRef.current !== xterm) return;
+
+						fitAddon.fit();
+						const cols = xterm.cols;
+						const rows = xterm.rows;
+
+						if (cols > 0 && rows > 0) {
+							// Resize down then up to guarantee SIGWINCH
+							resizeRef.current({ paneId, cols, rows: rows - 1 });
+							setTimeout(() => {
+								if (xtermRef.current !== xterm) return;
+								resizeRef.current({ paneId, cols, rows });
+								// Force xterm to repaint after SIGWINCH completes
+								xterm.refresh(0, rows - 1);
+							}, 100);
+						}
+					});
+				});
+
+				// Use snapshot.cwd if available, otherwise parse from content
+				if (result.snapshot?.cwd) {
+					updateCwdRef.current(result.snapshot.cwd);
+				} else {
+					updateCwdRef.current(initialAnsi);
+				}
+				return; // Skip normal snapshot flow
+			}
+
+			// xterm.write() is asynchronous - escape sequences may not be fully
+			// processed when the terminal first renders, causing garbled display.
+			// Force a re-render after write completes to ensure correct display.
+			// (Symptom: restored terminals show corrupted text until resized)
+			// Use fitAddon.fit() and (when using WebGL) clear the glyph atlas to force a full repaint.
+			xterm.write(initialAnsi, () => {
+				const redraw = () => {
+					requestAnimationFrame(() => {
+						try {
+							if (restoreSequenceRef.current !== restoreSequence) return;
+							if (xtermRef.current !== xterm) return;
+
+							fitAddon.fit();
+							if (xtermRef.current !== xterm) return;
+
+							// Reattached sessions can sometimes render partially until the user resizes the pane.
+							// WebGL off fully fixes this, which strongly suggests a WebGL texture-atlas repaint bug.
+							// Clearing the atlas forces xterm-webgl to rebuild glyphs and repaint without a resize nudge.
+							const cols = xterm.cols;
+							const rows = xterm.rows;
+							if (cols <= 0 || rows <= 0) return;
+
+							// Keep PTY dimensions in sync even when FitAddon doesn't change cols/rows.
+							resizeRef.current({ paneId, cols, rows });
+
+							if (!result.isNew) {
+								const renderer = rendererRef.current?.current;
+								if (renderer?.kind === "webgl") {
+									// Clear twice: once immediately, and once after fonts settle.
+									// This reduces restore artifacts (especially for TUIs like opencode)
+									// and prevents stale glyphs when fonts swap in.
+									renderer.clearTextureAtlas?.();
+								}
+							}
+							xterm.refresh(0, rows - 1);
+						} catch (error) {
+							console.warn(
+								"[Terminal] redraw() failed after restoration:",
+								error,
+							);
+						}
+					});
+				};
+
+				// Redraw once immediately, and once again after fonts settle.
+				redraw();
+				void document.fonts?.ready.then(() => {
+					if (restoreSequenceRef.current !== restoreSequence) return;
+					if (xtermRef.current !== xterm) return;
+					redraw();
+				});
+
+				// Enable streaming AFTER xterm has processed the snapshot.
+				// This prevents live PTY output from interleaving with snapshot replay.
+				isStreamReadyRef.current = true;
+				flushPendingEvents();
+			});
+			// Use snapshot.cwd if available, otherwise parse from content
+			if (result.snapshot?.cwd) {
+				updateCwdRef.current(result.snapshot.cwd);
+			} else {
+				updateCwdRef.current(initialAnsi);
+			}
+		} catch (error) {
+			console.error("[Terminal] Restoration failed:", error);
+		}
+	}, [flushPendingEvents, paneId]);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: createOrAttachRef used intentionally to read latest value without recreating callback
+	const handleRetryConnection = useCallback(() => {
+		setConnectionError(null);
+		const xterm = xtermRef.current;
+		if (!xterm) return;
+
+		isStreamReadyRef.current = false;
+		pendingInitialStateRef.current = null;
+
+		xterm.clear();
+		xterm.writeln("Retrying connection...\r\n");
+
+		createOrAttachRef.current(
+			{
+				paneId,
+				tabId: parentTabIdRef.current || paneId,
+				workspaceId,
+				cols: xterm.cols,
+				rows: xterm.rows,
+			},
+			{
+				onSuccess: (result) => {
+					setConnectionError(null);
+					pendingInitialStateRef.current = result;
+					maybeApplyInitialState();
+				},
+				onError: (error) => {
+					setConnectionError(error.message || "Connection failed");
+					isStreamReadyRef.current = true;
+					flushPendingEvents();
+				},
+			},
+		);
+	}, [
+		paneId,
+		workspaceId,
+		maybeApplyInitialState,
+		flushPendingEvents,
+		setConnectionError,
+	]);
+
 	const handleStreamData = (event: TerminalStreamEvent) => {
 		// Queue events until terminal is ready to prevent data loss
-		if (!xtermRef.current || !subscriptionEnabled) {
+		if (!xtermRef.current || !isStreamReadyRef.current) {
 			pendingEventsRef.current.push(event);
 			return;
 		}
 
 		if (event.type === "data") {
+			updateModesFromDataRef.current(event.data);
 			xtermRef.current.write(event.data);
 			updateCwdFromData(event.data);
 		} else if (event.type === "exit") {
 			isExitedRef.current = true;
-			setSubscriptionEnabled(false);
+			isStreamReadyRef.current = false;
 			xtermRef.current.writeln(
 				`\r\n\r\n[Process exited with code ${event.exitCode}]`,
 			);
 			xtermRef.current.writeln("[Press any key to restart]");
+		} else if (event.type === "disconnect") {
+			// Daemon connection lost - show error UI with retry option
+			setConnectionError(event.reason || "Connection to terminal daemon lost");
+		} else if (event.type === "error") {
+			const message = event.code
+				? `${event.code}: ${event.error}`
+				: event.error;
+			console.warn("[Terminal] stream error:", message);
+
+			toast.error("Terminal error", {
+				description: message,
+			});
+
+			if (event.code === "WRITE_QUEUE_FULL" || event.code === "WRITE_FAILED") {
+				xtermRef.current.writeln(`\r\n[Terminal] ${message}`);
+			} else {
+				setConnectionError(message);
+			}
 		}
 	};
 
@@ -243,25 +636,40 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 		[isFocused],
 	);
 
+	// biome-ignore lint/correctness/useExhaustiveDependencies: refs (writeRef, resizeRef, detachRef, clearScrollbackRef, createOrAttachRef) used intentionally to read latest values without resubscribing
 	useEffect(() => {
 		const container = terminalRef.current;
 		if (!container) return;
 
+		// Cancel any pending detach from a previous unmount (e.g., React StrictMode's
+		// simulated unmount/remount cycle). This prevents the detach from corrupting
+		// the terminal state when we're immediately remounting.
+		const pendingDetach = pendingDetaches.get(paneId);
+		if (pendingDetach) {
+			clearTimeout(pendingDetach);
+			pendingDetaches.delete(paneId);
+		}
+
 		let isUnmounted = false;
 
 		const {
 			xterm,
 			fitAddon,
+			renderer,
 			cleanup: cleanupQuerySuppression,
 		} = createTerminalInstance(container, {
-			cwd: workspaceCwd,
+			cwd: workspaceCwdRef.current,
 			initialTheme: initialThemeRef.current,
 			onFileLinkClick: (path, line, column) =>
 				handleFileLinkClickRef.current(path, line, column),
 		});
 		xtermRef.current = xterm;
 		fitAddonRef.current = fitAddon;
+		rendererRef.current = renderer;
 		isExitedRef.current = false;
+		isStreamReadyRef.current = false;
+		didFirstRenderRef.current = false;
+		pendingInitialStateRef.current = null;
 
 		if (isFocusedRef.current) {
 			xterm.focus();
@@ -274,37 +682,37 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 			searchAddonRef.current = searchAddon;
 		});
 
-		const flushPendingEvents = () => {
-			if (pendingEventsRef.current.length === 0) return;
-			const events = pendingEventsRef.current.splice(
-				0,
-				pendingEventsRef.current.length,
-			);
-			for (const event of events) {
-				if (event.type === "data") {
-					xterm.write(event.data);
-					updateCwdRef.current(event.data);
-				} else {
-					isExitedRef.current = true;
-					setSubscriptionEnabled(false);
-					xterm.writeln(`\r\n\r\n[Process exited with code ${event.exitCode}]`);
-					xterm.writeln("[Press any key to restart]");
-				}
+		// Wait for xterm to render once before applying restoration data.
+		// This prevents crashes when writing rehydrate escape sequences too early.
+		renderDisposableRef.current?.dispose();
+		let firstRenderFallback: ReturnType<typeof setTimeout> | null = null;
+
+		renderDisposableRef.current = xterm.onRender(() => {
+			if (firstRenderFallback) {
+				clearTimeout(firstRenderFallback);
+				firstRenderFallback = null;
 			}
-		};
+			renderDisposableRef.current?.dispose();
+			renderDisposableRef.current = null;
+			didFirstRenderRef.current = true;
+			maybeApplyInitialState();
+		});
 
-		const applyInitialState = (result: {
-			wasRecovered: boolean;
-			isNew: boolean;
-			scrollback: string;
-		}) => {
-			xterm.write(result.scrollback);
-			updateCwdRef.current(result.scrollback);
-		};
+		// Failure-proofing: if the renderer never emits an initial render (e.g. WebGL hiccup,
+		// offscreen mount), don't leave the session stuck in "not ready" forever.
+		firstRenderFallback = setTimeout(() => {
+			if (isUnmounted) return;
+			if (didFirstRenderRef.current) return;
+			didFirstRenderRef.current = true;
+			maybeApplyInitialState();
+		}, FIRST_RENDER_RESTORE_FALLBACK_MS);
 
 		const restartTerminal = () => {
 			isExitedRef.current = false;
-			setSubscriptionEnabled(false);
+			isStreamReadyRef.current = false;
+			isAlternateScreenRef.current = false; // Reset for new shell
+			isBracketedPasteRef.current = false;
+			modeScanBufferRef.current = "";
 			xterm.clear();
 			createOrAttachRef.current(
 				{
@@ -316,12 +724,14 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 				},
 				{
 					onSuccess: (result) => {
-						applyInitialState(result);
-						setSubscriptionEnabled(true);
-						flushPendingEvents();
+						pendingInitialStateRef.current = result;
+						maybeApplyInitialState();
 					},
-					onError: () => {
-						setSubscriptionEnabled(true);
+					onError: (error) => {
+						console.error("[Terminal] Failed to restart:", error);
+						setConnectionError(error.message || "Failed to restart terminal");
+						isStreamReadyRef.current = true;
+						flushPendingEvents();
 					},
 				},
 			);
@@ -341,9 +751,16 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 		}) => {
 			const { domEvent } = event;
 			if (domEvent.key === "Enter") {
-				const title = sanitizeForTitle(commandBufferRef.current);
-				if (title && parentTabIdRef.current) {
-					debouncedSetTabAutoTitleRef.current(parentTabIdRef.current, title);
+				// Don't auto-title from keyboard when in alternate screen (TUI apps like vim, codex)
+				// TUI apps set their own title via escape sequences handled by onTitleChange
+				// Use our own tracking (isAlternateScreenRef) because xterm.buffer.active.type
+				// is unreliable after HMR or recovery - the new xterm instance doesn't know
+				// about escape sequences that were sent before it was created.
+				if (!isAlternateScreenRef.current) {
+					const title = sanitizeForTitle(commandBufferRef.current);
+					if (title && parentTabIdRef.current) {
+						debouncedSetTabAutoTitleRef.current(parentTabIdRef.current, title);
+					}
 				}
 				commandBufferRef.current = "";
 			} else if (domEvent.key === "Backspace") {
@@ -378,14 +795,16 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 					if (initialCommands || initialCwd) {
 						clearPaneInitialDataRef.current(paneId);
 					}
-					// Always apply initial state (scrollback) first, then flush pending events
-					// This ensures we don't lose terminal history when reattaching
-					applyInitialState(result);
-					setSubscriptionEnabled(true);
-					flushPendingEvents();
+					// Defer initial state restoration until xterm has rendered once.
+					// Streaming is enabled only after restoration is queued into xterm.
+					pendingInitialStateRef.current = result;
+					maybeApplyInitialState();
 				},
-				onError: () => {
-					setSubscriptionEnabled(true);
+				onError: (error) => {
+					console.error("[Terminal] Failed to create/attach:", error);
+					setConnectionError(error.message || "Failed to connect to terminal");
+					isStreamReadyRef.current = true;
+					flushPendingEvents();
 				},
 			},
 		);
@@ -438,10 +857,15 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 			onPaste: (text) => {
 				commandBufferRef.current += text;
 			},
+			onWrite: handleWrite,
+			isBracketedPasteEnabled: () => isBracketedPasteRef.current,
 		});
 
 		return () => {
 			isUnmounted = true;
+			if (firstRenderFallback) {
+				clearTimeout(firstRenderFallback);
+			}
 			inputDisposable.dispose();
 			keyDisposable.dispose();
 			titleDisposable.dispose();
@@ -453,14 +877,45 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 			cleanupQuerySuppression();
 			unregisterClearCallbackRef.current(paneId);
 			debouncedSetTabAutoTitleRef.current?.cancel?.();
-			// Detach instead of kill to keep PTY running for reattachment
-			detachRef.current({ paneId });
-			setSubscriptionEnabled(false);
-			xterm.dispose();
+
+			// Debounce detach to handle React StrictMode's unmount/remount cycle.
+			// If the component remounts quickly (as in StrictMode), the new mount will
+			// cancel this timeout, preventing the detach from corrupting terminal state.
+			const detachTimeout = setTimeout(() => {
+				detachRef.current({ paneId });
+				pendingDetaches.delete(paneId);
+			}, 50);
+			pendingDetaches.set(paneId, detachTimeout);
+
+			isStreamReadyRef.current = false;
+			didFirstRenderRef.current = false;
+			pendingInitialStateRef.current = null;
+			isAlternateScreenRef.current = false;
+			isBracketedPasteRef.current = false;
+			modeScanBufferRef.current = "";
+			renderDisposableRef.current?.dispose();
+			renderDisposableRef.current = null;
+
+			// Delay xterm.dispose() to let internal timeouts complete.
+			// xterm.open() schedules a setTimeout for Viewport.syncScrollArea.
+			// If we dispose synchronously, that timeout fires after _renderer is
+			// cleared, causing "Cannot read properties of undefined (reading 'dimensions')".
+			// Using setTimeout(0) ensures our dispose runs after xterm's internal callback.
+			setTimeout(() => {
+				xterm.dispose();
+			}, 0);
+
 			xtermRef.current = null;
 			searchAddonRef.current = null;
+			rendererRef.current = null;
 		};
-	}, [paneId, workspaceId, workspaceCwd]);
+	}, [
+		paneId,
+		workspaceId,
+		flushPendingEvents,
+		maybeApplyInitialState,
+		setConnectionError,
+	]);
 
 	useEffect(() => {
 		const xterm = xtermRef.current;
@@ -503,6 +958,21 @@ export const Terminal = ({ tabId, workspaceId }: TerminalProps) => {
 				isOpen={isSearchOpen}
 				onClose={() => setIsSearchOpen(false)}
 			/>
+			{connectionError && (
+				<div className="absolute inset-0 z-10 flex flex-col items-center justify-center bg-black/80">
+					<div className="mb-4 px-4 text-center text-red-400">
+						<p className="font-semibold">Connection Error</p>
+						<p className="mt-1 text-sm text-gray-400">{connectionError}</p>
+					</div>
+					<button
+						type="button"
+						onClick={handleRetryConnection}
+						className="rounded-md bg-blue-600 px-4 py-2 text-sm text-white transition-colors hover:bg-blue-700"
+					>
+						Retry Connection
+					</button>
+				</div>
+			)}
 			<div ref={terminalRef} className="h-full w-full" />
 		</div>
 	);
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/helpers.ts b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/helpers.ts
index 89473cdf9d6..179fb5d16f7 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/helpers.ts
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/helpers.ts
@@ -60,35 +60,87 @@ export function getDefaultTerminalBg(): string {
  * Load GPU-accelerated renderer with automatic fallback.
  * Tries WebGL first, falls back to Canvas if WebGL fails.
  */
-function loadRenderer(xterm: XTerm): { dispose: () => void } {
+export type TerminalRenderer = {
+	kind: "webgl" | "canvas" | "dom";
+	dispose: () => void;
+	clearTextureAtlas?: () => void;
+};
+
+type PreferredRenderer = TerminalRenderer["kind"] | "auto";
+
+function getPreferredRenderer(): PreferredRenderer {
+	try {
+		const stored = localStorage.getItem("terminal-renderer");
+		if (stored === "webgl" || stored === "canvas" || stored === "dom") {
+			return stored;
+		}
+	} catch {
+		// ignore
+	}
+
+	// Default: avoid xterm-webgl on macOS. We've seen repeated corruption/glitching
+	// when terminals are hidden/shown or switched between panes.
+	return navigator.userAgent.includes("Macintosh") ? "canvas" : "webgl";
+}
+
+function loadRenderer(xterm: XTerm): TerminalRenderer {
 	let renderer: WebglAddon | CanvasAddon | null = null;
+	let webglAddon: WebglAddon | null = null;
+	let kind: TerminalRenderer["kind"] = "dom";
+
+	const preferred = getPreferredRenderer();
+
+	if (preferred === "dom") {
+		return { kind: "dom", dispose: () => {}, clearTextureAtlas: undefined };
+	}
+
+	const tryLoadCanvas = () => {
+		try {
+			renderer = new CanvasAddon();
+			xterm.loadAddon(renderer);
+			kind = "canvas";
+		} catch {
+			// Canvas fallback failed, use default renderer
+		}
+	};
+
+	if (preferred === "canvas") {
+		tryLoadCanvas();
+		return {
+			kind,
+			dispose: () => renderer?.dispose(),
+			clearTextureAtlas: undefined,
+		};
+	}
 
 	try {
-		const webglAddon = new WebglAddon();
+		webglAddon = new WebglAddon();
 
 		webglAddon.onContextLoss(() => {
-			webglAddon.dispose();
-			try {
-				renderer = new CanvasAddon();
-				xterm.loadAddon(renderer);
-			} catch {
-				// Canvas fallback failed, use default renderer
-			}
+			webglAddon?.dispose();
+			webglAddon = null;
+			tryLoadCanvas();
 		});
 
 		xterm.loadAddon(webglAddon);
 		renderer = webglAddon;
+		kind = "webgl";
 	} catch {
-		try {
-			renderer = new CanvasAddon();
-			xterm.loadAddon(renderer);
-		} catch {
-			// Both renderers failed, use default
-		}
+		tryLoadCanvas();
 	}
 
 	return {
+		kind,
 		dispose: () => renderer?.dispose(),
+		clearTextureAtlas: webglAddon
+			? () => {
+					try {
+						webglAddon?.clearTextureAtlas();
+					} catch (error) {
+						console.warn("[Terminal] WebGL clearTextureAtlas() failed:", error);
+					}
+				}
+			: undefined,
 	};
 }
 
@@ -98,12 +150,21 @@ export interface CreateTerminalOptions {
 	onFileLinkClick?: (path: string, line?: number, column?: number) => void;
 }
 
+/**
+ * Mutable reference to the terminal renderer.
+ * Used because the GPU renderer is loaded asynchronously after the terminal is created.
+ */
+export interface TerminalRendererRef {
+	current: TerminalRenderer;
+}
+
 export function createTerminalInstance(
 	container: HTMLDivElement,
 	options: CreateTerminalOptions = {},
 ): {
 	xterm: XTerm;
 	fitAddon: FitAddon;
+	renderer: TerminalRendererRef;
 	cleanup: () => void;
 } {
 	const { cwd, initialTheme, onFileLinkClick } = options;
@@ -118,17 +179,44 @@ export function createTerminalInstance(
 	const unicode11Addon = new Unicode11Addon();
 	const imageAddon = new ImageAddon();
 
+	// Track cleanup state to prevent operations on disposed terminal
+	let isDisposed = false;
+	let rafId: number | null = null;
+
+	// Use a ref pattern so the renderer can be updated after rAF.
+	// Start with a no-op DOM renderer - the actual GPU renderer is loaded async.
+	const rendererRef: TerminalRendererRef = {
+		current: {
+			kind: "dom",
+			dispose: () => {},
+			clearTextureAtlas: undefined,
+		},
+	};
+
 	xterm.open(container);
 
+	// Load non-renderer addons synchronously - these are safe and needed immediately
 	xterm.loadAddon(fitAddon);
-	const renderer = loadRenderer(xterm);
-
 	xterm.loadAddon(clipboardAddon);
 	xterm.loadAddon(unicode11Addon);
 	xterm.loadAddon(imageAddon);
 
+	// Defer GPU renderer loading to next animation frame.
+	// xterm.open() schedules a setTimeout for Viewport.syncScrollArea which expects
+	// the renderer to be ready. Loading WebGL/Canvas immediately after open() can
+	// cause a race condition where the setTimeout fires during addon initialization,
+	// when _renderer is temporarily undefined (old renderer disposed, new not yet set).
+	// Deferring to rAF ensures xterm's internal setTimeout completes first with the
+	// default DOM renderer, then we safely swap to WebGL/Canvas.
+	rafId = requestAnimationFrame(() => {
+		rafId = null;
+		if (isDisposed) return;
+		rendererRef.current = loadRenderer(xterm);
+	});
+
 	import("@xterm/addon-ligatures")
 		.then(({ LigaturesAddon }) => {
+			if (isDisposed) return;
 			try {
 				xterm.loadAddon(new LigaturesAddon());
 			} catch {
@@ -178,9 +266,14 @@ export function createTerminalInstance(
 	return {
 		xterm,
 		fitAddon,
+		renderer: rendererRef,
 		cleanup: () => {
+			isDisposed = true;
+			if (rafId !== null) {
+				cancelAnimationFrame(rafId);
+			}
 			cleanupQuerySuppression();
-			renderer.dispose();
+			rendererRef.current.dispose();
 		},
 	};
 }
@@ -195,6 +288,10 @@ export interface KeyboardHandlerOptions {
 export interface PasteHandlerOptions {
 	/** Callback when text is pasted, receives the pasted text */
 	onPaste?: (text: string) => void;
+	/** Optional direct write callback to bypass xterm's paste burst */
+	onWrite?: (data: string) => void;
+	/** Whether bracketed paste mode is enabled for the current terminal */
+	isBracketedPasteEnabled?: () => boolean;
 }
 
 /**
@@ -218,6 +315,8 @@ export function setupPasteHandler(
 	const textarea = xterm.textarea;
 	if (!textarea) return () => {};
 
+	let cancelActivePaste: (() => void) | null = null;
+
 	const handlePaste = (event: ClipboardEvent) => {
 		const text = event.clipboardData?.getData("text/plain");
 		if (!text) return;
@@ -226,12 +325,100 @@ export function setupPasteHandler(
 		event.stopImmediatePropagation();
 
 		options.onPaste?.(text);
-		xterm.paste(text);
+
+		// Cancel any in-flight chunked paste to avoid overlapping writes.
+		cancelActivePaste?.();
+		cancelActivePaste = null;
+
+		// Chunk large pastes to avoid sending a single massive input burst that can
+		// overwhelm the PTY pipeline (especially when the app is repainting heavily).
+		const MAX_SYNC_PASTE_CHARS = 16_384;
+
+		// If no direct write callback is provided, fall back to xterm's paste()
+		// (it handles newline normalization and bracketed paste mode internally).
+		if (!options.onWrite) {
+			const CHUNK_CHARS = 4096;
+			const CHUNK_DELAY_MS = 5;
+
+			if (text.length <= MAX_SYNC_PASTE_CHARS) {
+				xterm.paste(text);
+				return;
+			}
+
+			let cancelled = false;
+			let offset = 0;
+
+			const pasteNext = () => {
+				if (cancelled) return;
+
+				const chunk = text.slice(offset, offset + CHUNK_CHARS);
+				offset += CHUNK_CHARS;
+				xterm.paste(chunk);
+
+				if (offset < text.length) {
+					setTimeout(pasteNext, CHUNK_DELAY_MS);
+				}
+			};
+
+			cancelActivePaste = () => {
+				cancelled = true;
+			};
+
+			pasteNext();
+			return;
+		}
+
+		// Direct write path: replicate xterm's paste normalization, but stream in
+		// controlled chunks while preserving bracketed-paste semantics.
+		const preparedText = text.replace(/\r?\n/g, "\r");
+		const bracketedPasteEnabled = options.isBracketedPasteEnabled?.() ?? false;
+		const shouldBracket = bracketedPasteEnabled;
+
+		// For small/medium pastes, preserve the fast path and avoid timers.
+		if (preparedText.length <= MAX_SYNC_PASTE_CHARS) {
+			options.onWrite(
+				shouldBracket ? `\x1b[200~${preparedText}\x1b[201~` : preparedText,
+			);
+			return;
+		}
+
+		let cancelled = false;
+		let offset = 0;
+		const CHUNK_CHARS = 16_384;
+		const CHUNK_DELAY_MS = 0;
+
+		const pasteNext = () => {
+			if (cancelled) return;
+
+			const chunk = preparedText.slice(offset, offset + CHUNK_CHARS);
+			offset += CHUNK_CHARS;
+
+			if (shouldBracket) {
+				// Wrap each chunk to avoid long-running "open" bracketed paste blocks,
+				// which some TUIs may defer repainting until the closing sequence arrives.
+				options.onWrite?.(`\x1b[200~${chunk}\x1b[201~`);
+			} else {
+				options.onWrite?.(chunk);
+			}
+
+			if (offset < preparedText.length) {
+				setTimeout(pasteNext, CHUNK_DELAY_MS);
+				return;
+			}
+		};
+
+		cancelActivePaste = () => {
+			cancelled = true;
+		};
+
+		pasteNext();
 	};
 
 	textarea.addEventListener("paste", handlePaste, { capture: true });
 
 	return () => {
+		cancelActivePaste?.();
+		cancelActivePaste = null;
 		textarea.removeEventListener("paste", handlePaste, { capture: true });
 	};
 }
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/index.ts b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/index.ts
new file mode 100644
index 00000000000..dc089375c36
--- /dev/null
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/index.ts
@@ -0,0 +1,2 @@
+export type { UseTerminalConnectionOptions } from "./useTerminalConnection";
+export { useTerminalConnection } from "./useTerminalConnection";
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/useTerminalConnection.ts b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/useTerminalConnection.ts
new file mode 100644
index 00000000000..f98bd58276f
--- /dev/null
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/useTerminalConnection.ts
@@ -0,0 +1,67 @@
+import { useRef, useState } from "react";
+import { trpc } from "renderer/lib/trpc";
+
+export interface UseTerminalConnectionOptions {
+	workspaceId: string;
+}
+
+/**
+ * Hook to manage terminal connection state and mutations.
+ *
+ * Encapsulates:
+ * - tRPC mutations (createOrAttach, write, resize, detach, clearScrollback)
+ * - Stable refs to mutation functions (to avoid re-renders)
+ * - Connection error state
+ * - Workspace CWD query
+ *
+ * NOTE: Stream subscription is intentionally NOT included here because it needs
+ * direct access to xterm refs for event handling. Keep that in the component.
+ */
+export function useTerminalConnection({
+	workspaceId,
+}: UseTerminalConnectionOptions) {
+	const [connectionError, setConnectionError] = useState<string | null>(null);
+
+	// tRPC mutations
+	const createOrAttachMutation = trpc.terminal.createOrAttach.useMutation();
+	const writeMutation = trpc.terminal.write.useMutation();
+	const resizeMutation = trpc.terminal.resize.useMutation();
+	const detachMutation = trpc.terminal.detach.useMutation();
+	const clearScrollbackMutation = trpc.terminal.clearScrollback.useMutation();
+
+	// Query for workspace cwd
+	const { data: workspaceCwd } =
+		trpc.terminal.getWorkspaceCwd.useQuery(workspaceId);
+
+	// Stable refs to mutation functions - these don't change identity on re-render
+	const createOrAttachRef = useRef(createOrAttachMutation.mutate);
+	const writeRef = useRef(writeMutation.mutate);
+	const resizeRef = useRef(resizeMutation.mutate);
+	const detachRef = useRef(detachMutation.mutate);
+	const clearScrollbackRef = useRef(clearScrollbackMutation.mutate);
+
+	// Keep refs up to date
+	createOrAttachRef.current = createOrAttachMutation.mutate;
+	writeRef.current = writeMutation.mutate;
+	resizeRef.current = resizeMutation.mutate;
+	detachRef.current = detachMutation.mutate;
+	clearScrollbackRef.current = clearScrollbackMutation.mutate;
+
+	return {
+		// Connection error state
+		connectionError,
+		setConnectionError,
+
+		// Workspace CWD from query
+		workspaceCwd,
+
+		// Stable refs to mutation functions (use these in effects/callbacks)
+		refs: {
+			createOrAttach: createOrAttachRef,
+			write: writeRef,
+			resize: resizeRef,
+			detach: detachRef,
+			clearScrollback: clearScrollbackRef,
+		},
+	};
+}
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/types.ts b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/types.ts
index 29e41dff6d5..f74da3d734b 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/types.ts
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/types.ts
@@ -5,4 +5,6 @@ export interface TerminalProps {
 
 export type TerminalStreamEvent =
 	| { type: "data"; data: string }
-	| { type: "exit"; exitCode: number };
+	| { type: "exit"; exitCode: number }
+	| { type: "disconnect"; reason: string }
+	| { type: "error"; error: string; code?: string };
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/index.tsx b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/index.tsx
index fb3908f55f4..8e1331e6ee0 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/index.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/index.tsx
@@ -6,19 +6,65 @@ import { TabView } from "./TabView";
 
 export function TabsContent() {
 	const { data: activeWorkspace } = trpc.workspaces.getActive.useQuery();
+	const { data: terminalPersistence } =
+		trpc.settings.getTerminalPersistence.useQuery();
 	const activeWorkspaceId = activeWorkspace?.id;
 	const allTabs = useTabsStore((s) => s.tabs);
 	const panes = useTabsStore((s) => s.panes);
 	const activeTabIds = useTabsStore((s) => s.activeTabIds);
 
+	const activeTabId = activeWorkspaceId
+		? activeTabIds[activeWorkspaceId]
+		: null;
+
+	// Get all tabs for current workspace (for fallback/empty check)
+	const currentWorkspaceTabs = useMemo(() => {
+		if (!activeWorkspaceId) return [];
+		return allTabs.filter((tab) => tab.workspaceId === activeWorkspaceId);
+	}, [activeWorkspaceId, allTabs]);
+
 	const tabToRender = useMemo(() => {
-		if (!activeWorkspaceId) return null;
-		const activeTabId = activeTabIds[activeWorkspaceId];
 		if (!activeTabId) return null;
-
 		return allTabs.find((tab) => tab.id === activeTabId) || null;
-	}, [activeWorkspaceId, activeTabIds, allTabs]);
+	}, [activeTabId, allTabs]);
+
+	// When terminal persistence is enabled, keep all terminals mounted across
+	// workspace/tab switches. This prevents TUI white screen issues by avoiding
+	// the unmount/remount cycle that requires complex reattach/rehydration logic.
+	// Uses visibility:hidden (not display:none) to preserve xterm dimensions.
+	if (terminalPersistence) {
+		// Show empty view only if current workspace has no tabs
+		if (currentWorkspaceTabs.length === 0) {
+			return <EmptyTabView />;
+		}
+
+		return (
+			<div className="relative h-full w-full">
+				{allTabs.map((tab) => {
+					// A tab is visible only if:
+					// 1. It belongs to the active workspace AND
+					// 2. It's the active tab for that workspace
+					const isVisible =
+						tab.workspaceId === activeWorkspaceId && tab.id === activeTabId;
+
+					return (
+						<div
+							key={tab.id}
+							className="absolute inset-0"
+							style={{
+								visibility: isVisible ? "visible" : "hidden",
+								pointerEvents: isVisible ? "auto" : "none",
+							}}
+						>
+							<TabView tab={tab} panes={panes} />
+						</div>
+					);
+				})}
+			</div>
+		);
+	}
 
+	// Original behavior when persistence disabled: only render active tab
 	if (!tabToRender) {
 		return <EmptyTabView />;
 	}
diff --git a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/Sidebar/TabsView/TabItem/index.tsx b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/Sidebar/TabsView/TabItem/index.tsx
index 07a860bed16..774ee9a9061 100644
--- a/apps/desktop/src/renderer/screens/main/components/WorkspaceView/Sidebar/TabsView/TabItem/index.tsx
+++ b/apps/desktop/src/renderer/screens/main/components/WorkspaceView/Sidebar/TabsView/TabItem/index.tsx
@@ -31,9 +31,15 @@ export function TabItem({ tab, index, isActive }: TabItemProps) {
 	const setActiveTab = useTabsStore((s) => s.setActiveTab);
 	const renameTab = useTabsStore((s) => s.renameTab);
 	const panes = useTabsStore((s) => s.panes);
-	const needsAttention = useTabsStore((s) =>
-		Object.values(s.panes).some((p) => p.tabId === tab.id && p.needsAttention),
-	);
+
+	// Derive aggregate status from panes in this tab (priority: permission > working > review)
+	const aggregateStatus = useTabsStore((s) => {
+		const tabPanes = Object.values(s.panes).filter((p) => p.tabId === tab.id);
+		if (tabPanes.some((p) => p.status === "permission")) return "permission";
+		if (tabPanes.some((p) => p.status === "working")) return "working";
+		if (tabPanes.some((p) => p.status === "review")) return "review";
+		return null;
+	});
 
 	const paneCount = useMemo(
 		() => Object.values(panes).filter((p) => p.tabId === tab.id).length,
@@ -190,15 +196,34 @@ export function TabItem({ tab, index, isActive }: TabItemProps) {
 						<HiMiniCommandLine className="size-4" />
 						<div className="flex items-center gap-1 flex-1 min-w-0">
 							<span className="truncate flex-1">{displayName}</span>
-							{needsAttention && (
+							{aggregateStatus && (
 								<Tooltip>
 									<TooltipTrigger asChild>
 										<span className="relative flex size-2 shrink-0 ml-1">
-											<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
-											<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+											{aggregateStatus === "permission" && (
+												<>
+													<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75" />
+													<span className="relative inline-flex size-2 rounded-full bg-red-500" />
+												</>
+											)}
+											{aggregateStatus === "working" && (
+												<>
+													<span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-amber-400 opacity-75" />
+													<span className="relative inline-flex size-2 rounded-full bg-amber-500" />
+												</>
+											)}
+											{aggregateStatus === "review" && (
+												<span className="relative inline-flex size-2 rounded-full bg-green-500" />
+											)}
 										</span>
 									</TooltipTrigger>
-									<TooltipContent side="right">Agent completed</TooltipContent>
+									<TooltipContent side="right">
+										{aggregateStatus === "permission"
+											? "Needs input"
+											: aggregateStatus === "working"
+												? "Agent working"
+												: "Ready for review"}
+									</TooltipContent>
 								</Tooltip>
 							)}
 						</div>
diff --git a/apps/desktop/src/renderer/stores/app-state.ts b/apps/desktop/src/renderer/stores/app-state.ts
index 296752c34d8..613d68052af 100644
--- a/apps/desktop/src/renderer/stores/app-state.ts
+++ b/apps/desktop/src/renderer/stores/app-state.ts
@@ -10,7 +10,8 @@ export type SettingsSection =
 	| "keyboard"
 	| "presets"
 	| "ringtones"
-	| "behavior";
+	| "behavior"
+	| "terminal";
 
 interface AppState {
 	currentView: AppView;
diff --git a/apps/desktop/src/renderer/stores/tabs/store.ts b/apps/desktop/src/renderer/stores/tabs/store.ts
index 6e6823d33e0..a9df51456fa 100644
--- a/apps/desktop/src/renderer/stores/tabs/store.ts
+++ b/apps/desktop/src/renderer/stores/tabs/store.ts
@@ -4,7 +4,12 @@ import { create } from "zustand";
 import { devtools, persist } from "zustand/middleware";
 import { trpcTabsStorage } from "../../lib/trpc-storage";
 import { movePaneToNewTab, movePaneToTab } from "./actions/move-pane";
-import type { AddFileViewerPaneOptions, TabsState, TabsStore } from "./types";
+import type {
+	AddFileViewerPaneOptions,
+	PaneStatus,
+	TabsState,
+	TabsStore,
+} from "./types";
 import {
 	type CreatePaneOptions,
 	createFileViewerPane,
@@ -199,14 +204,22 @@ export const useTabsStore = create<TabsStore>()(
 						];
 					}
 
-					// Clear needsAttention for the focused pane in the tab being activated
-					const focusedPaneId = state.focusedPaneIds[tabId];
+					// Clear attention status for panes in the selected tab
+					const tabPaneIds = extractPaneIdsFromLayout(tab.layout);
 					const newPanes = { ...state.panes };
-					if (focusedPaneId && newPanes[focusedPaneId]?.needsAttention) {
-						newPanes[focusedPaneId] = {
-							...newPanes[focusedPaneId],
-							needsAttention: false,
-						};
+					let hasChanges = false;
+					for (const paneId of tabPaneIds) {
+						const currentStatus = newPanes[paneId]?.status;
+						if (currentStatus === "review") {
+							// User acknowledged completion
+							newPanes[paneId] = { ...newPanes[paneId], status: "idle" };
+							hasChanges = true;
+						} else if (currentStatus === "permission") {
+							// Assume permission granted, agent is now working
+							newPanes[paneId] = { ...newPanes[paneId], status: "working" };
+							hasChanges = true;
+						}
+						// "working" status is NOT cleared by click - persists until Stop
 					}
 
 					set({
@@ -218,7 +231,7 @@ export const useTabsStore = create<TabsStore>()(
 							...state.tabHistoryStacks,
 							[workspaceId]: newHistoryStack,
 						},
-						panes: newPanes,
+						...(hasChanges ? { panes: newPanes } : {}),
 					});
 				},
 
@@ -504,20 +517,11 @@ export const useTabsStore = create<TabsStore>()(
 					const pane = state.panes[paneId];
 					if (!pane || pane.tabId !== tabId) return;
 
-					// Clear needsAttention for the pane being focused
-					const newPanes = pane.needsAttention
-						? {
-								...state.panes,
-								[paneId]: { ...pane, needsAttention: false },
-							}
-						: state.panes;
-
 					set({
 						focusedPaneIds: {
 							...state.focusedPaneIds,
 							[tabId]: paneId,
 						},
-						panes: newPanes,
 					});
 				},
 
@@ -532,18 +536,18 @@ export const useTabsStore = create<TabsStore>()(
 					}));
 				},
 
-				setNeedsAttention: (paneId, needsAttention) => {
+				setPaneStatus: (paneId, status) => {
 					set((state) => ({
 						panes: {
 							...state.panes,
 							[paneId]: state.panes[paneId]
-								? { ...state.panes[paneId], needsAttention }
+								? { ...state.panes[paneId], status }
 								: state.panes[paneId],
 						},
 					}));
 				},
 
-				clearWorkspaceAttention: (workspaceId) => {
+				clearWorkspaceAttentionStatus: (workspaceId) => {
 					const state = get();
 					const workspaceTabs = state.tabs.filter(
 						(t) => t.workspaceId === workspaceId,
@@ -559,10 +563,17 @@ export const useTabsStore = create<TabsStore>()(
 					const newPanes = { ...state.panes };
 					let hasChanges = false;
 					for (const paneId of workspacePaneIds) {
-						if (newPanes[paneId]?.needsAttention) {
-							newPanes[paneId] = { ...newPanes[paneId], needsAttention: false };
+						const currentStatus = newPanes[paneId]?.status;
+						if (currentStatus === "review") {
+							// User acknowledged completion
+							newPanes[paneId] = { ...newPanes[paneId], status: "idle" };
+							hasChanges = true;
+						} else if (currentStatus === "permission") {
+							// Assume permission granted, Claude is now working
+							newPanes[paneId] = { ...newPanes[paneId], status: "working" };
 							hasChanges = true;
 						}
+						// "working" status is NOT cleared by click - persists until Stop
 					}
 
 					if (hasChanges) {
@@ -774,7 +785,35 @@ export const useTabsStore = create<TabsStore>()(
 			}),
 			{
 				name: "tabs-storage",
+				version: 2,
 				storage: trpcTabsStorage,
+				migrate: (persistedState, version) => {
+					const state = persistedState as TabsState;
+					if (version < 2 && state.panes) {
+						// Migrate needsAttention → status
+						for (const pane of Object.values(state.panes)) {
+							// biome-ignore lint/suspicious/noExplicitAny: migration from old schema
+							const legacyPane = pane as any;
+							if (legacyPane.needsAttention === true) {
+								pane.status = "review";
+							}
+							delete legacyPane.needsAttention;
+						}
+					}
+					return state;
+				},
+				merge: (persistedState, currentState) => {
+					const persisted = persistedState as TabsState;
+					// Clear stale "working" status on startup - agent can't be working if app just started
+					if (persisted.panes) {
+						for (const pane of Object.values(persisted.panes)) {
+							if (pane.status === "working") {
+								pane.status = "idle";
+							}
+						}
+					}
+					return { ...currentState, ...persisted };
+				},
 			},
 		),
 		{ name: "TabsStore" },
diff --git a/apps/desktop/src/renderer/stores/tabs/types.ts b/apps/desktop/src/renderer/stores/tabs/types.ts
index 64a298ab958..33c01dfceb6 100644
--- a/apps/desktop/src/renderer/stores/tabs/types.ts
+++ b/apps/desktop/src/renderer/stores/tabs/types.ts
@@ -1,9 +1,15 @@
 import type { MosaicBranch, MosaicNode } from "react-mosaic-component";
 import type { ChangeCategory } from "shared/changes-types";
-import type { BaseTab, BaseTabsState, Pane, PaneType } from "shared/tabs-types";
+import type {
+	BaseTab,
+	BaseTabsState,
+	Pane,
+	PaneStatus,
+	PaneType,
+} from "shared/tabs-types";
 
 // Re-export shared types
-export type { Pane, PaneType };
+export type { Pane, PaneStatus, PaneType };
 
 /**
  * A Tab is a container that holds one or more Panes in a Mosaic layout.
@@ -69,8 +75,8 @@ export interface TabsStore extends TabsState {
 	removePane: (paneId: string) => void;
 	setFocusedPane: (tabId: string, paneId: string) => void;
 	markPaneAsUsed: (paneId: string) => void;
-	setNeedsAttention: (paneId: string, needsAttention: boolean) => void;
-	clearWorkspaceAttention: (workspaceId: string) => void;
+	setPaneStatus: (paneId: string, status: PaneStatus) => void;
+	clearWorkspaceAttentionStatus: (workspaceId: string) => void;
 	updatePaneCwd: (
 		paneId: string,
 		cwd: string | null,
diff --git a/apps/desktop/src/renderer/stores/tabs/useAgentHookListener.ts b/apps/desktop/src/renderer/stores/tabs/useAgentHookListener.ts
index 0b158830c49..033e152796d 100644
--- a/apps/desktop/src/renderer/stores/tabs/useAgentHookListener.ts
+++ b/apps/desktop/src/renderer/stores/tabs/useAgentHookListener.ts
@@ -8,7 +8,7 @@ import { resolveNotificationTarget } from "./utils/resolve-notification-target";
 
 /**
  * Hook that listens for notification events via tRPC subscription.
- * Handles agent completions and focus requests from native notifications.
+ * Handles agent lifecycle events (Start, Stop, PermissionRequest) and focus requests.
  */
 export function useAgentHookListener() {
 	const setActiveWorkspace = useSetActiveWorkspace();
@@ -28,17 +28,36 @@ export function useAgentHookListener() {
 
 			const { paneId, workspaceId } = target;
 
-			if (event.type === NOTIFICATION_EVENTS.AGENT_COMPLETE) {
+			if (event.type === NOTIFICATION_EVENTS.AGENT_LIFECYCLE) {
 				if (!paneId) return;
 
-				const activeTabId = state.activeTabIds[workspaceId];
-				const focusedPaneId = activeTabId && state.focusedPaneIds[activeTabId];
-				const isAlreadyActive =
-					activeWorkspaceRef.current?.id === workspaceId &&
-					focusedPaneId === paneId;
+				const lifecycleEvent = event.data;
+				if (!lifecycleEvent) return;
 
-				if (!isAlreadyActive) {
-					state.setNeedsAttention(paneId, true);
+				const { eventType } = lifecycleEvent;
+
+				if (eventType === "Start") {
+					// Agent started working - always set to working
+					state.setPaneStatus(paneId, "working");
+				} else if (eventType === "PermissionRequest") {
+					// Agent needs permission - always set to permission (overrides working)
+					state.setPaneStatus(paneId, "permission");
+				} else if (eventType === "Stop") {
+					// Agent completed - only mark as review if not currently active
+					const activeTabId = state.activeTabIds[workspaceId];
+					const focusedPaneId =
+						activeTabId && state.focusedPaneIds[activeTabId];
+					const isAlreadyActive =
+						activeWorkspaceRef.current?.id === workspaceId &&
+						focusedPaneId === paneId;
+
+					if (isAlreadyActive) {
+						// User is watching - go straight to idle
+						state.setPaneStatus(paneId, "idle");
+					} else {
+						// User not watching - mark for review
+						state.setPaneStatus(paneId, "review");
+					}
 				}
 			} else if (event.type === NOTIFICATION_EVENTS.FOCUS_TAB) {
 				const appState = useAppStore.getState();
diff --git a/apps/desktop/src/shared/constants.ts b/apps/desktop/src/shared/constants.ts
index 35c6207de41..4a9dca35899 100644
--- a/apps/desktop/src/shared/constants.ts
+++ b/apps/desktop/src/shared/constants.ts
@@ -40,7 +40,7 @@ export const CONFIG_TEMPLATE = `{
 }`;
 
 export const NOTIFICATION_EVENTS = {
-	AGENT_COMPLETE: "agent-complete",
+	AGENT_LIFECYCLE: "agent-lifecycle",
 	FOCUS_TAB: "focus-tab",
 } as const;
 
diff --git a/apps/desktop/src/shared/tabs-types.ts b/apps/desktop/src/shared/tabs-types.ts
index d38ce4c4284..f55cd73ceaa 100644
--- a/apps/desktop/src/shared/tabs-types.ts
+++ b/apps/desktop/src/shared/tabs-types.ts
@@ -10,6 +10,15 @@ import type { ChangeCategory } from "./changes-types";
  */
 export type PaneType = "terminal" | "webview" | "file-viewer";
 
+/**
+ * Pane status for agent lifecycle indicators
+ * - idle: No indicator shown (default)
+ * - working: Agent actively processing (amber)
+ * - permission: Agent blocked, needs user action (red)
+ * - review: Agent completed, ready for review (green)
+ */
+export type PaneStatus = "idle" | "working" | "permission" | "review";
+
 /**
  * File viewer display modes
  */
@@ -49,7 +58,7 @@ export interface Pane {
 	type: PaneType;
 	name: string;
 	isNew?: boolean;
-	needsAttention?: boolean;
+	status?: PaneStatus;
 	initialCommands?: string[];
 	initialCwd?: string;
 	url?: string; // For webview panes
diff --git a/bun.lock b/bun.lock
index 4b961cccc2d..23d7b50fbfd 100644
--- a/bun.lock
+++ b/bun.lock
@@ -156,6 +156,7 @@
         "@xterm/addon-unicode11": "^0.8.0",
         "@xterm/addon-web-links": "^0.11.0",
         "@xterm/addon-webgl": "^0.18.0",
+        "@xterm/headless": "^5.5.0",
         "@xterm/xterm": "^5.5.0",
         "better-sqlite3": "12.5.0",
         "bindings": "^1.5.0",
@@ -1635,6 +1636,8 @@
 
     "@xterm/addon-webgl": ["@xterm/addon-webgl@0.18.0", "", { "peerDependencies": { "@xterm/xterm": "^5.0.0" } }, "sha512-xCnfMBTI+/HKPdRnSOHaJDRqEpq2Ugy8LEj9GiY4J3zJObo3joylIFaMvzBwbYRg8zLtkO0KQaStCeSfoaI2/w=="],
 
+    "@xterm/headless": ["@xterm/headless@5.5.0", "", {}, "sha512-5xXB7kdQlFBP82ViMJTwwEc3gKCLGKR/eoxQm4zge7GPBl86tCdI0IdPJjoKd8mUSFXz5V7i/25sfsEkP4j46g=="],
+
     "@xterm/xterm": ["@xterm/xterm@5.5.0", "", {}, "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A=="],
 
     "@xtuc/ieee754": ["@xtuc/ieee754@1.2.0", "", {}, "sha512-DX8nKgqcGwsc0eJSqYt5lwP4DH5FlHnmuWWBRy7X0NcaGR0ZtuyeESgMwTYVEtxmsNGY+qit4QYT/MIYTOTPeA=="],
diff --git a/packages/local-db/drizzle/0004_add_terminal_link_behavior_setting.sql b/packages/local-db/drizzle/0004_add_terminal_link_behavior_setting.sql
deleted file mode 100644
index ad70f21f3fe..00000000000
--- a/packages/local-db/drizzle/0004_add_terminal_link_behavior_setting.sql
+++ /dev/null
@@ -1 +0,0 @@
-ALTER TABLE `settings` ADD `terminal_link_behavior` text;
\ No newline at end of file
diff --git a/packages/local-db/drizzle/0004_settings_workspace_improvements.sql b/packages/local-db/drizzle/0004_settings_workspace_improvements.sql
new file mode 100644
index 00000000000..cd5007742b4
--- /dev/null
+++ b/packages/local-db/drizzle/0004_settings_workspace_improvements.sql
@@ -0,0 +1,4 @@
+ALTER TABLE `settings` ADD `terminal_link_behavior` text;--> statement-breakpoint
+ALTER TABLE `settings` ADD `navigation_style` text;--> statement-breakpoint
+ALTER TABLE `settings` ADD `terminal_persistence` integer;--> statement-breakpoint
+ALTER TABLE `workspaces` ADD `is_unread` integer DEFAULT false;
\ No newline at end of file
diff --git a/packages/local-db/drizzle/0005_add_navigation_style.sql b/packages/local-db/drizzle/0005_add_navigation_style.sql
deleted file mode 100644
index c3c175a0327..00000000000
--- a/packages/local-db/drizzle/0005_add_navigation_style.sql
+++ /dev/null
@@ -1 +0,0 @@
-ALTER TABLE `settings` ADD `navigation_style` text;
\ No newline at end of file
diff --git a/packages/local-db/drizzle/0006_add_unique_branch_workspace_index.sql b/packages/local-db/drizzle/0006_add_unique_branch_workspace_index.sql
deleted file mode 100644
index 6945d545ce6..00000000000
--- a/packages/local-db/drizzle/0006_add_unique_branch_workspace_index.sql
+++ /dev/null
@@ -1,46 +0,0 @@
--- Dedupe existing duplicate branch workspaces before creating unique index.
--- Keep the most recently used one (highest last_opened_at), with id ASC as tiebreaker.
--- First, update settings.last_active_workspace_id if it points to a workspace we're about to delete
-UPDATE settings
-SET last_active_workspace_id = (
-    SELECT w1.id FROM workspaces w1
-    WHERE w1.type = 'branch'
-    AND w1.project_id = (
-        SELECT w2.project_id FROM workspaces w2 WHERE w2.id = settings.last_active_workspace_id
-    )
-    ORDER BY w1.last_opened_at DESC NULLS LAST, w1.id ASC
-    LIMIT 1
-)
-WHERE last_active_workspace_id IN (
-    SELECT w1.id FROM workspaces w1
-    WHERE w1.type = 'branch'
-    AND EXISTS (
-        SELECT 1 FROM workspaces w2
-        WHERE w2.type = 'branch'
-        AND w2.project_id = w1.project_id
-        AND (
-            w2.last_opened_at > w1.last_opened_at
-            OR (w2.last_opened_at = w1.last_opened_at AND w2.id < w1.id)
-            OR (w2.last_opened_at IS NOT NULL AND w1.last_opened_at IS NULL)
-        )
-    )
-);
-
--- Delete duplicate branch workspaces, keeping the most recently used per project
--- Survivor selection: highest last_opened_at, then lowest id as tiebreaker
-DELETE FROM workspaces
-WHERE type = 'branch'
-AND id NOT IN (
-    SELECT id FROM (
-        SELECT id, ROW_NUMBER() OVER (
-            PARTITION BY project_id
-            ORDER BY last_opened_at DESC NULLS LAST, id ASC
-        ) as rn
-        FROM workspaces
-        WHERE type = 'branch'
-    ) ranked
-    WHERE rn = 1
-);
-
--- Now safe to create the unique index
-CREATE UNIQUE INDEX IF NOT EXISTS `workspaces_unique_branch_per_project` ON `workspaces` (`project_id`) WHERE `type` = 'branch';
diff --git a/packages/local-db/drizzle/0007_add_workspace_is_unread.sql b/packages/local-db/drizzle/0007_add_workspace_is_unread.sql
deleted file mode 100644
index 9f3ca8ec300..00000000000
--- a/packages/local-db/drizzle/0007_add_workspace_is_unread.sql
+++ /dev/null
@@ -1 +0,0 @@
-ALTER TABLE `workspaces` ADD `is_unread` integer DEFAULT false;
diff --git a/packages/local-db/drizzle/meta/0004_snapshot.json b/packages/local-db/drizzle/meta/0004_snapshot.json
index 991b5469eb5..a51da6b146a 100644
--- a/packages/local-db/drizzle/meta/0004_snapshot.json
+++ b/packages/local-db/drizzle/meta/0004_snapshot.json
@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "bb9f9f85-bcbb-4003-b20f-4c172a1c6fc8",
+  "id": "334d24a4-5204-4d61-904a-bdd0498a401d",
   "prevId": "d5a52ac9-bc1e-4529-89bf-5748d4df5006",
   "tables": {
     "organization_members": {
@@ -340,6 +340,20 @@
           "primaryKey": false,
           "notNull": false,
           "autoincrement": false
+        },
+        "navigation_style": {
+          "name": "navigation_style",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "terminal_persistence": {
+          "name": "terminal_persistence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
         }
       },
       "indexes": {},
@@ -811,6 +825,14 @@
           "primaryKey": false,
           "notNull": true,
           "autoincrement": false
+        },
+        "is_unread": {
+          "name": "is_unread",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": false
         }
       },
       "indexes": {
diff --git a/packages/local-db/drizzle/meta/0005_snapshot.json b/packages/local-db/drizzle/meta/0005_snapshot.json
deleted file mode 100644
index 14c02c328fd..00000000000
--- a/packages/local-db/drizzle/meta/0005_snapshot.json
+++ /dev/null
@@ -1,984 +0,0 @@
-{
-  "version": "6",
-  "dialect": "sqlite",
-  "id": "ac200b80-657f-4cd7-b338-2d6adeb925e7",
-  "prevId": "bb9f9f85-bcbb-4003-b20f-4c172a1c6fc8",
-  "tables": {
-    "organization_members": {
-      "name": "organization_members",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "user_id": {
-          "name": "user_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "role": {
-          "name": "role",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organization_members_organization_id_idx": {
-          "name": "organization_members_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "organization_members_user_id_idx": {
-          "name": "organization_members_user_id_idx",
-          "columns": [
-            "user_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "organization_members_organization_id_organizations_id_fk": {
-          "name": "organization_members_organization_id_organizations_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "organization_members_user_id_users_id_fk": {
-          "name": "organization_members_user_id_users_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "users",
-          "columnsFrom": [
-            "user_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "organizations": {
-      "name": "organizations",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_org_id": {
-          "name": "clerk_org_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "github_org": {
-          "name": "github_org",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organizations_clerk_org_id_unique": {
-          "name": "organizations_clerk_org_id_unique",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_unique": {
-          "name": "organizations_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_idx": {
-          "name": "organizations_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "organizations_clerk_org_id_idx": {
-          "name": "organizations_clerk_org_id_idx",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "projects": {
-      "name": "projects",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "main_repo_path": {
-          "name": "main_repo_path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "color": {
-          "name": "color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "config_toast_dismissed": {
-          "name": "config_toast_dismissed",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "default_branch": {
-          "name": "default_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "projects_main_repo_path_idx": {
-          "name": "projects_main_repo_path_idx",
-          "columns": [
-            "main_repo_path"
-          ],
-          "isUnique": false
-        },
-        "projects_last_opened_at_idx": {
-          "name": "projects_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "settings": {
-      "name": "settings",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "integer",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false,
-          "default": 1
-        },
-        "last_active_workspace_id": {
-          "name": "last_active_workspace_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_used_app": {
-          "name": "last_used_app",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets": {
-          "name": "terminal_presets",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets_initialized": {
-          "name": "terminal_presets_initialized",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "selected_ringtone_id": {
-          "name": "selected_ringtone_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "active_organization_id": {
-          "name": "active_organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "confirm_on_quit": {
-          "name": "confirm_on_quit",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_link_behavior": {
-          "name": "terminal_link_behavior",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "navigation_style": {
-          "name": "navigation_style",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "tasks": {
-      "name": "tasks",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "title": {
-          "name": "title",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "description": {
-          "name": "description",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status": {
-          "name": "status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "status_color": {
-          "name": "status_color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_type": {
-          "name": "status_type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_position": {
-          "name": "status_position",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "priority": {
-          "name": "priority",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "repository_id": {
-          "name": "repository_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "assignee_id": {
-          "name": "assignee_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "creator_id": {
-          "name": "creator_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "estimate": {
-          "name": "estimate",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "due_date": {
-          "name": "due_date",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "labels": {
-          "name": "labels",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "pr_url": {
-          "name": "pr_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_provider": {
-          "name": "external_provider",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_id": {
-          "name": "external_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_key": {
-          "name": "external_key",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_url": {
-          "name": "external_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_synced_at": {
-          "name": "last_synced_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "sync_error": {
-          "name": "sync_error",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "started_at": {
-          "name": "started_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "completed_at": {
-          "name": "completed_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "tasks_slug_unique": {
-          "name": "tasks_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "tasks_slug_idx": {
-          "name": "tasks_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "tasks_organization_id_idx": {
-          "name": "tasks_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_assignee_id_idx": {
-          "name": "tasks_assignee_id_idx",
-          "columns": [
-            "assignee_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_status_idx": {
-          "name": "tasks_status_idx",
-          "columns": [
-            "status"
-          ],
-          "isUnique": false
-        },
-        "tasks_created_at_idx": {
-          "name": "tasks_created_at_idx",
-          "columns": [
-            "created_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "tasks_organization_id_organizations_id_fk": {
-          "name": "tasks_organization_id_organizations_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "tasks_assignee_id_users_id_fk": {
-          "name": "tasks_assignee_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "assignee_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "set null",
-          "onUpdate": "no action"
-        },
-        "tasks_creator_id_users_id_fk": {
-          "name": "tasks_creator_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "creator_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "users": {
-      "name": "users",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_id": {
-          "name": "clerk_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "email": {
-          "name": "email",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "users_clerk_id_unique": {
-          "name": "users_clerk_id_unique",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": true
-        },
-        "users_email_unique": {
-          "name": "users_email_unique",
-          "columns": [
-            "email"
-          ],
-          "isUnique": true
-        },
-        "users_email_idx": {
-          "name": "users_email_idx",
-          "columns": [
-            "email"
-          ],
-          "isUnique": false
-        },
-        "users_clerk_id_idx": {
-          "name": "users_clerk_id_idx",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "workspaces": {
-      "name": "workspaces",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "worktree_id": {
-          "name": "worktree_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "type": {
-          "name": "type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "workspaces_project_id_idx": {
-          "name": "workspaces_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_worktree_id_idx": {
-          "name": "workspaces_worktree_id_idx",
-          "columns": [
-            "worktree_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_last_opened_at_idx": {
-          "name": "workspaces_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "workspaces_project_id_projects_id_fk": {
-          "name": "workspaces_project_id_projects_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "workspaces_worktree_id_worktrees_id_fk": {
-          "name": "workspaces_worktree_id_worktrees_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "worktrees",
-          "columnsFrom": [
-            "worktree_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "worktrees": {
-      "name": "worktrees",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "path": {
-          "name": "path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "base_branch": {
-          "name": "base_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "git_status": {
-          "name": "git_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "github_status": {
-          "name": "github_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "worktrees_project_id_idx": {
-          "name": "worktrees_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "worktrees_branch_idx": {
-          "name": "worktrees_branch_idx",
-          "columns": [
-            "branch"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "worktrees_project_id_projects_id_fk": {
-          "name": "worktrees_project_id_projects_id_fk",
-          "tableFrom": "worktrees",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    }
-  },
-  "views": {},
-  "enums": {},
-  "_meta": {
-    "schemas": {},
-    "tables": {},
-    "columns": {}
-  },
-  "internal": {
-    "indexes": {}
-  }
-}
\ No newline at end of file
diff --git a/packages/local-db/drizzle/meta/0006_snapshot.json b/packages/local-db/drizzle/meta/0006_snapshot.json
deleted file mode 100644
index 5362480f6e2..00000000000
--- a/packages/local-db/drizzle/meta/0006_snapshot.json
+++ /dev/null
@@ -1,984 +0,0 @@
-{
-  "version": "6",
-  "dialect": "sqlite",
-  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
-  "prevId": "ac200b80-657f-4cd7-b338-2d6adeb925e7",
-  "tables": {
-    "organization_members": {
-      "name": "organization_members",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "user_id": {
-          "name": "user_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "role": {
-          "name": "role",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organization_members_organization_id_idx": {
-          "name": "organization_members_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "organization_members_user_id_idx": {
-          "name": "organization_members_user_id_idx",
-          "columns": [
-            "user_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "organization_members_organization_id_organizations_id_fk": {
-          "name": "organization_members_organization_id_organizations_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "organization_members_user_id_users_id_fk": {
-          "name": "organization_members_user_id_users_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "users",
-          "columnsFrom": [
-            "user_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "organizations": {
-      "name": "organizations",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_org_id": {
-          "name": "clerk_org_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "github_org": {
-          "name": "github_org",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organizations_clerk_org_id_unique": {
-          "name": "organizations_clerk_org_id_unique",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_unique": {
-          "name": "organizations_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_idx": {
-          "name": "organizations_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "organizations_clerk_org_id_idx": {
-          "name": "organizations_clerk_org_id_idx",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "projects": {
-      "name": "projects",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "main_repo_path": {
-          "name": "main_repo_path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "color": {
-          "name": "color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "config_toast_dismissed": {
-          "name": "config_toast_dismissed",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "default_branch": {
-          "name": "default_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "projects_main_repo_path_idx": {
-          "name": "projects_main_repo_path_idx",
-          "columns": [
-            "main_repo_path"
-          ],
-          "isUnique": false
-        },
-        "projects_last_opened_at_idx": {
-          "name": "projects_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "settings": {
-      "name": "settings",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "integer",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false,
-          "default": 1
-        },
-        "last_active_workspace_id": {
-          "name": "last_active_workspace_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_used_app": {
-          "name": "last_used_app",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets": {
-          "name": "terminal_presets",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets_initialized": {
-          "name": "terminal_presets_initialized",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "selected_ringtone_id": {
-          "name": "selected_ringtone_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "active_organization_id": {
-          "name": "active_organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "confirm_on_quit": {
-          "name": "confirm_on_quit",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_link_behavior": {
-          "name": "terminal_link_behavior",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "navigation_style": {
-          "name": "navigation_style",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "tasks": {
-      "name": "tasks",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "title": {
-          "name": "title",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "description": {
-          "name": "description",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status": {
-          "name": "status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "status_color": {
-          "name": "status_color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_type": {
-          "name": "status_type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_position": {
-          "name": "status_position",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "priority": {
-          "name": "priority",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "repository_id": {
-          "name": "repository_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "assignee_id": {
-          "name": "assignee_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "creator_id": {
-          "name": "creator_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "estimate": {
-          "name": "estimate",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "due_date": {
-          "name": "due_date",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "labels": {
-          "name": "labels",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "pr_url": {
-          "name": "pr_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_provider": {
-          "name": "external_provider",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_id": {
-          "name": "external_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_key": {
-          "name": "external_key",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_url": {
-          "name": "external_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_synced_at": {
-          "name": "last_synced_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "sync_error": {
-          "name": "sync_error",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "started_at": {
-          "name": "started_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "completed_at": {
-          "name": "completed_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "tasks_slug_unique": {
-          "name": "tasks_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "tasks_slug_idx": {
-          "name": "tasks_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "tasks_organization_id_idx": {
-          "name": "tasks_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_assignee_id_idx": {
-          "name": "tasks_assignee_id_idx",
-          "columns": [
-            "assignee_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_status_idx": {
-          "name": "tasks_status_idx",
-          "columns": [
-            "status"
-          ],
-          "isUnique": false
-        },
-        "tasks_created_at_idx": {
-          "name": "tasks_created_at_idx",
-          "columns": [
-            "created_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "tasks_organization_id_organizations_id_fk": {
-          "name": "tasks_organization_id_organizations_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "tasks_assignee_id_users_id_fk": {
-          "name": "tasks_assignee_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "assignee_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "set null",
-          "onUpdate": "no action"
-        },
-        "tasks_creator_id_users_id_fk": {
-          "name": "tasks_creator_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "creator_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "users": {
-      "name": "users",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_id": {
-          "name": "clerk_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "email": {
-          "name": "email",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "users_clerk_id_unique": {
-          "name": "users_clerk_id_unique",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": true
-        },
-        "users_email_unique": {
-          "name": "users_email_unique",
-          "columns": [
-            "email"
-          ],
-          "isUnique": true
-        },
-        "users_email_idx": {
-          "name": "users_email_idx",
-          "columns": [
-            "email"
-          ],
-          "isUnique": false
-        },
-        "users_clerk_id_idx": {
-          "name": "users_clerk_id_idx",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "workspaces": {
-      "name": "workspaces",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "worktree_id": {
-          "name": "worktree_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "type": {
-          "name": "type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "workspaces_project_id_idx": {
-          "name": "workspaces_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_worktree_id_idx": {
-          "name": "workspaces_worktree_id_idx",
-          "columns": [
-            "worktree_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_last_opened_at_idx": {
-          "name": "workspaces_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "workspaces_project_id_projects_id_fk": {
-          "name": "workspaces_project_id_projects_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "workspaces_worktree_id_worktrees_id_fk": {
-          "name": "workspaces_worktree_id_worktrees_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "worktrees",
-          "columnsFrom": [
-            "worktree_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "worktrees": {
-      "name": "worktrees",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "path": {
-          "name": "path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "base_branch": {
-          "name": "base_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "git_status": {
-          "name": "git_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "github_status": {
-          "name": "github_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "worktrees_project_id_idx": {
-          "name": "worktrees_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "worktrees_branch_idx": {
-          "name": "worktrees_branch_idx",
-          "columns": [
-            "branch"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "worktrees_project_id_projects_id_fk": {
-          "name": "worktrees_project_id_projects_id_fk",
-          "tableFrom": "worktrees",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    }
-  },
-  "views": {},
-  "enums": {},
-  "_meta": {
-    "schemas": {},
-    "tables": {},
-    "columns": {}
-  },
-  "internal": {
-    "indexes": {}
-  }
-}
diff --git a/packages/local-db/drizzle/meta/0007_snapshot.json b/packages/local-db/drizzle/meta/0007_snapshot.json
deleted file mode 100644
index dbf24a697c3..00000000000
--- a/packages/local-db/drizzle/meta/0007_snapshot.json
+++ /dev/null
@@ -1,992 +0,0 @@
-{
-  "version": "6",
-  "dialect": "sqlite",
-  "id": "a7b8c9d0-e1f2-3456-7890-abcdef123456",
-  "prevId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
-  "tables": {
-    "organization_members": {
-      "name": "organization_members",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "user_id": {
-          "name": "user_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "role": {
-          "name": "role",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organization_members_organization_id_idx": {
-          "name": "organization_members_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "organization_members_user_id_idx": {
-          "name": "organization_members_user_id_idx",
-          "columns": [
-            "user_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "organization_members_organization_id_organizations_id_fk": {
-          "name": "organization_members_organization_id_organizations_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "organization_members_user_id_users_id_fk": {
-          "name": "organization_members_user_id_users_id_fk",
-          "tableFrom": "organization_members",
-          "tableTo": "users",
-          "columnsFrom": [
-            "user_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "organizations": {
-      "name": "organizations",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_org_id": {
-          "name": "clerk_org_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "github_org": {
-          "name": "github_org",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "organizations_clerk_org_id_unique": {
-          "name": "organizations_clerk_org_id_unique",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_unique": {
-          "name": "organizations_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "organizations_slug_idx": {
-          "name": "organizations_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "organizations_clerk_org_id_idx": {
-          "name": "organizations_clerk_org_id_idx",
-          "columns": [
-            "clerk_org_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "projects": {
-      "name": "projects",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "main_repo_path": {
-          "name": "main_repo_path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "color": {
-          "name": "color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "config_toast_dismissed": {
-          "name": "config_toast_dismissed",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "default_branch": {
-          "name": "default_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "projects_main_repo_path_idx": {
-          "name": "projects_main_repo_path_idx",
-          "columns": [
-            "main_repo_path"
-          ],
-          "isUnique": false
-        },
-        "projects_last_opened_at_idx": {
-          "name": "projects_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "settings": {
-      "name": "settings",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "integer",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false,
-          "default": 1
-        },
-        "last_active_workspace_id": {
-          "name": "last_active_workspace_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_used_app": {
-          "name": "last_used_app",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets": {
-          "name": "terminal_presets",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_presets_initialized": {
-          "name": "terminal_presets_initialized",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "selected_ringtone_id": {
-          "name": "selected_ringtone_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "active_organization_id": {
-          "name": "active_organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "confirm_on_quit": {
-          "name": "confirm_on_quit",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "terminal_link_behavior": {
-          "name": "terminal_link_behavior",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "navigation_style": {
-          "name": "navigation_style",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "tasks": {
-      "name": "tasks",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "slug": {
-          "name": "slug",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "title": {
-          "name": "title",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "description": {
-          "name": "description",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status": {
-          "name": "status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "status_color": {
-          "name": "status_color",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_type": {
-          "name": "status_type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "status_position": {
-          "name": "status_position",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "priority": {
-          "name": "priority",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "organization_id": {
-          "name": "organization_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "repository_id": {
-          "name": "repository_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "assignee_id": {
-          "name": "assignee_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "creator_id": {
-          "name": "creator_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "estimate": {
-          "name": "estimate",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "due_date": {
-          "name": "due_date",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "labels": {
-          "name": "labels",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "pr_url": {
-          "name": "pr_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_provider": {
-          "name": "external_provider",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_id": {
-          "name": "external_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_key": {
-          "name": "external_key",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "external_url": {
-          "name": "external_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "last_synced_at": {
-          "name": "last_synced_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "sync_error": {
-          "name": "sync_error",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "started_at": {
-          "name": "started_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "completed_at": {
-          "name": "completed_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "tasks_slug_unique": {
-          "name": "tasks_slug_unique",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": true
-        },
-        "tasks_slug_idx": {
-          "name": "tasks_slug_idx",
-          "columns": [
-            "slug"
-          ],
-          "isUnique": false
-        },
-        "tasks_organization_id_idx": {
-          "name": "tasks_organization_id_idx",
-          "columns": [
-            "organization_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_assignee_id_idx": {
-          "name": "tasks_assignee_id_idx",
-          "columns": [
-            "assignee_id"
-          ],
-          "isUnique": false
-        },
-        "tasks_status_idx": {
-          "name": "tasks_status_idx",
-          "columns": [
-            "status"
-          ],
-          "isUnique": false
-        },
-        "tasks_created_at_idx": {
-          "name": "tasks_created_at_idx",
-          "columns": [
-            "created_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "tasks_organization_id_organizations_id_fk": {
-          "name": "tasks_organization_id_organizations_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "organizations",
-          "columnsFrom": [
-            "organization_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "tasks_assignee_id_users_id_fk": {
-          "name": "tasks_assignee_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "assignee_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "set null",
-          "onUpdate": "no action"
-        },
-        "tasks_creator_id_users_id_fk": {
-          "name": "tasks_creator_id_users_id_fk",
-          "tableFrom": "tasks",
-          "tableTo": "users",
-          "columnsFrom": [
-            "creator_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "users": {
-      "name": "users",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "clerk_id": {
-          "name": "clerk_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "email": {
-          "name": "email",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "avatar_url": {
-          "name": "avatar_url",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "deleted_at": {
-          "name": "deleted_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "users_clerk_id_unique": {
-          "name": "users_clerk_id_unique",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": true
-        },
-        "users_email_unique": {
-          "name": "users_email_unique",
-          "columns": [
-            "email"
-          ],
-          "isUnique": true
-        },
-        "users_email_idx": {
-          "name": "users_email_idx",
-          "columns": [
-            "email"
-          ],
-          "isUnique": false
-        },
-        "users_clerk_id_idx": {
-          "name": "users_clerk_id_idx",
-          "columns": [
-            "clerk_id"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "workspaces": {
-      "name": "workspaces",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "worktree_id": {
-          "name": "worktree_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "type": {
-          "name": "type",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "name": {
-          "name": "name",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "tab_order": {
-          "name": "tab_order",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "last_opened_at": {
-          "name": "last_opened_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "is_unread": {
-          "name": "is_unread",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false,
-          "default": false
-        }
-      },
-      "indexes": {
-        "workspaces_project_id_idx": {
-          "name": "workspaces_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_worktree_id_idx": {
-          "name": "workspaces_worktree_id_idx",
-          "columns": [
-            "worktree_id"
-          ],
-          "isUnique": false
-        },
-        "workspaces_last_opened_at_idx": {
-          "name": "workspaces_last_opened_at_idx",
-          "columns": [
-            "last_opened_at"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "workspaces_project_id_projects_id_fk": {
-          "name": "workspaces_project_id_projects_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        },
-        "workspaces_worktree_id_worktrees_id_fk": {
-          "name": "workspaces_worktree_id_worktrees_id_fk",
-          "tableFrom": "workspaces",
-          "tableTo": "worktrees",
-          "columnsFrom": [
-            "worktree_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    },
-    "worktrees": {
-      "name": "worktrees",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "text",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "project_id": {
-          "name": "project_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "path": {
-          "name": "path",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "branch": {
-          "name": "branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "base_branch": {
-          "name": "base_branch",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "git_status": {
-          "name": "git_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        },
-        "github_status": {
-          "name": "github_status",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false,
-          "autoincrement": false
-        }
-      },
-      "indexes": {
-        "worktrees_project_id_idx": {
-          "name": "worktrees_project_id_idx",
-          "columns": [
-            "project_id"
-          ],
-          "isUnique": false
-        },
-        "worktrees_branch_idx": {
-          "name": "worktrees_branch_idx",
-          "columns": [
-            "branch"
-          ],
-          "isUnique": false
-        }
-      },
-      "foreignKeys": {
-        "worktrees_project_id_projects_id_fk": {
-          "name": "worktrees_project_id_projects_id_fk",
-          "tableFrom": "worktrees",
-          "tableTo": "projects",
-          "columnsFrom": [
-            "project_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
-          "onDelete": "cascade",
-          "onUpdate": "no action"
-        }
-      },
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    }
-  },
-  "views": {},
-  "enums": {},
-  "_meta": {
-    "schemas": {},
-    "tables": {},
-    "columns": {}
-  },
-  "internal": {
-    "indexes": {}
-  }
-}
diff --git a/packages/local-db/drizzle/meta/_journal.json b/packages/local-db/drizzle/meta/_journal.json
index c63757dc471..ee19d4da90e 100644
--- a/packages/local-db/drizzle/meta/_journal.json
+++ b/packages/local-db/drizzle/meta/_journal.json
@@ -33,29 +33,8 @@
     {
       "idx": 4,
       "version": "6",
-      "when": 1767166138761,
-      "tag": "0004_add_terminal_link_behavior_setting",
-      "breakpoints": true
-    },
-    {
-      "idx": 5,
-      "version": "6",
-      "when": 1767166547886,
-      "tag": "0005_add_navigation_style",
-      "breakpoints": true
-    },
-    {
-      "idx": 6,
-      "version": "6",
-      "when": 1767230000000,
-      "tag": "0006_add_unique_branch_workspace_index",
-      "breakpoints": true
-    },
-    {
-      "idx": 7,
-      "version": "6",
-      "when": 1767350000000,
-      "tag": "0007_add_workspace_is_unread",
+      "when": 1767370047298,
+      "tag": "0004_settings_workspace_improvements",
       "breakpoints": true
     }
   ]
diff --git a/packages/local-db/src/schema/schema.ts b/packages/local-db/src/schema/schema.ts
index b5437dd783d..ae7ce71bba4 100644
--- a/packages/local-db/src/schema/schema.ts
+++ b/packages/local-db/src/schema/schema.ts
@@ -138,6 +138,7 @@ export const settings = sqliteTable("settings", {
 		"terminal_link_behavior",
 	).$type<TerminalLinkBehavior>(),
 	navigationStyle: text("navigation_style").$type<NavigationStyle>(),
+	terminalPersistence: integer("terminal_persistence", { mode: "boolean" }),
 });
 
 export type InsertSettings = typeof settings.$inferInsert;
diff --git a/thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md b/thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md
new file mode 100644
index 00000000000..f9ee095e214
--- /dev/null
+++ b/thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md
@@ -0,0 +1,57 @@
+---
+created: 2026-01-02T21:00:00Z
+last_updated: 2026-01-02T11:15:00Z
+session_count: 3
+status: COMPLETED
+---
+
+# Session: TUI White Screen on Workspace Switch
+
+## Goal
+Fix the remaining white screen issue when switching back to a workspace with an active TUI (vim, opencode, claude). Currently requires manual resize to fix.
+
+## Constraints
+- Must not regress the original fix (gibberish text on tab switch)
+- Must work with Canvas renderer (macOS default)
+- Should minimize visual flash during reattach
+
+## Key Decisions
+- Decision 1: Using SIGWINCH approach instead of snapshots for TUI restoration (snapshots don't capture styled spaces)
+- Decision 2: Need to ensure alt-screen is fully entered before flushing pending events
+- Decision 3: **FINAL** - Keep terminals mounted instead of unmount/remount cycle (Oracle insight: "The moment you create a *new* xterm on remount, you lose emulator state")
+
+## State
+- Done: [x] Captured problem statement + prior fix summary
+- Done: [x] Identified alt-screen reattach path in Terminal.tsx
+- Done: [x] Analyzed timing of current reattach flow
+- Done: [x] Identified 3 likely root causes (ranked by probability)
+- Done: [x] Consulted Oracle - discovered fundamental issue with unmount/remount
+- Done: [x] Implemented "keep terminals mounted" solution
+- Done: [x] Added memory warning to settings
+- Done: [x] Removed debug logging
+- Done: [x] Updated technical documentation
+- Done: [x] User verified: "omg everything feels buttery smooth now!"
+
+- Complete: [✓] **BUG RESOLVED**
+
+## Resolution Summary
+
+**Root Cause:** The SIGWINCH approach was fundamentally fragile. React unmounts Terminal components on workspace switch, destroying xterm.js instances. New xterm on remount loses all emulator state - race conditions were inevitable.
+
+**Solution:** Keep all terminal components mounted across workspace/tab switches. Use CSS `visibility: hidden` for inactive tabs. Gate behind `terminalPersistence` setting.
+
+**Files Modified:**
+- `TabsContent/index.tsx` - Render all tabs, hide inactive with CSS
+- `TerminalSettings.tsx` - Added memory warning
+- `Terminal.tsx` - Removed debug logging, kept SIGWINCH as fallback for app restart
+- `2026-01-02-terminal-persistence-technical-notes.md` - Documented approach
+
+## Open Questions (Answered)
+- ~~Is xterm.write("\x1b[?1049h") async issue the primary cause?~~ **No - fundamental unmount issue**
+- ~~Are container dimensions 0 during workspace switch?~~ **Moot - terminals stay mounted**
+- ~~Does xterm.refresh() help after SIGWINCH?~~ **Moot - no more remount cycle**
+
+## Working Set
+- Branch: `persistent-terminals`
+- PR: #541
+- Status: Changes ready to commit
diff --git a/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T12-58-19.md b/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T12-58-19.md
new file mode 100644
index 00000000000..e7423bb6d51
--- /dev/null
+++ b/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T12-58-19.md
@@ -0,0 +1,31 @@
+---
+type: auto-handoff
+date: 2026-01-02T12:58:19.863Z
+session_name: tui-white-screen
+trigger: pre-compact (opencode)
+---
+
+# Auto-Handoff: [→] Implement diagnostic logging to confirm root cause
+
+This handoff was automatically created before context compaction.
+
+## In Progress
+
+[→] Implement diagnostic logging to confirm root cause
+
+## Recent Completed
+
+[x] Captured problem statement + prior fix summary
+- Done: [x] Identified alt-screen reattach path in Terminal.tsx
+- Done: [x] Analyzed timing of current reattach flow
+- Done: [x] Identified 3 likely root causes (ranked by probability)
+
+## Resume Instructions
+
+1. Read this handoff to understand current state
+2. Check the ledger for full context: thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md
+3. Continue from where you left off
+
+## Source Ledger
+
+/Users/andreasasprou/.superset/worktrees/superset/persistent-terminals/thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md
diff --git a/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T14-14-50.md b/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T14-14-50.md
new file mode 100644
index 00000000000..e038ed0c66e
--- /dev/null
+++ b/thoughts/shared/handoffs/tui-white-screen/auto-handoff-2026-01-02T14-14-50.md
@@ -0,0 +1,31 @@
+---
+type: auto-handoff
+date: 2026-01-02T14:14:50.011Z
+session_name: tui-white-screen
+trigger: pre-compact (opencode)
+---
+
+# Auto-Handoff: [→] Implement diagnostic logging to confirm root cause
+
+This handoff was automatically created before context compaction.
+
+## In Progress
+
+[→] Implement diagnostic logging to confirm root cause
+
+## Recent Completed
+
+[x] Captured problem statement + prior fix summary
+- Done: [x] Identified alt-screen reattach path in Terminal.tsx
+- Done: [x] Analyzed timing of current reattach flow
+- Done: [x] Identified 3 likely root causes (ranked by probability)
+
+## Resume Instructions
+
+1. Read this handoff to understand current state
+2. Check the ledger for full context: thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md
+3. Continue from where you left off
+
+## Source Ledger
+
+/Users/andreasasprou/.superset/worktrees/superset/persistent-terminals/thoughts/ledgers/CONTINUITY_CLAUDE-tui-white-screen.md