Context

The usePtyHost checkbox is intended to let testers route PTY spawns through an isolated Electron UtilityProcess to avoid Electron main-process state inheritance issues, especially Claude Code v2.1.113+ on macOS.

The current implementation now covers the immediate experimental path: Phase 0 Claude shell wrapper, ptyHost spawning behind the setting/env flag, flow-control ack repair, host-ready handshake, restart cap hardening, and manager-state-preserving respawn.

Remaining work before calling ptyHost production-complete

• Validate packaged macOS builds with usePtyHost enabled. UtilityProcess entry path and native node-pty loading must be verified in the packaged app, not just dev.
• Validate Windows and WSL paths. Confirm wsl.exe cwd handling, WSLENV, GIT_COMMITTER_*, PANE_*, WORKTREE_PATH, and conpty behavior match legacy PTY behavior.
• Add integration or harness coverage for PtyHostSupervisor startup/restart. Unit tests currently cover flow-control only; supervisor behavior still needs a real or mocked UtilityProcess test seam.
• Add manual or automated crash-respawn validation. Kill the ptyHost with live terminal, Claude, run-command, and legacy terminal-session processes and verify expected respawn or skip behavior.
• Decide whether to implement true ptyHost-to-renderer byte delivery. Current architecture isolates PTY spawning but still routes bytes ptyHost -> main -> renderer MessagePort so main can keep DEC 2026 filtering, scrollback persistence, alt-screen, idle tracking, and flow control semantics. A true direct tee needs careful design to avoid raw-byte/TUI regressions.
• Add heavy-output validation, e.g. yes | head -c 50M, with the checkbox enabled to confirm pause/resume backpressure and renderer responsiveness.
• Add TUI regression validation for alternate screen apps and DEC Mode 2026 synchronized output.
• Consider consolidating duplicated PtyHandle shim code across terminal panels, CLI manager, run commands, and terminal sessions once behavior stabilizes.

Acceptance criteria

• usePtyHost enabled works in packaged macOS, Linux, Windows, and WSL smoke tests.
• Claude Code v2.1.113+ launches from Pane on macOS both in Claude panels and when typed into a terminal panel.
• Heavy output does not permanently stall or visibly stutter.
• ptyHost crash restarts within the bounded retry policy and live processes recover according to documented behavior.
• Existing terminal UX, scrollback persistence, alt-screen tracking, idle/activity state, and DEC 2026 filtering do not regress.
• Follow-up tests cover flow-control and supervisor restart behavior.