fix: restore terminal state after remote→local mode switch

[tomstetson]

Summary

Fixes the most-reported bug in Happy CLI: terminal input corruption after switching from remote mode (mobile) back to local mode via double-space. Users experience dropped characters, phantom mode switches, and an unresponsive Claude session.

• Fixes Bug Report: Terminal input corruption after switching from remote to local mode #301, Bug: Input handler persists after remote-to-local mode switch #422, Terminal input stuck after exit (raw mode not restored) #423, After switching back to local mode, the input is starting to getting incomplete. #424, Competing processes when switching to local mode #430, Happy crashes when switching input devices to local mode #443, Moving from remote mode to local mode removes the history and harm the writing in local mode #527

Root cause analysis

Five independent bugs compound to corrupt stdin during the remote→local transition:

#	Bug	Effect
1	Wrong cleanup order — raw mode disabled before Ink unmounts	Ink expects raw mode during teardown; disabling it first causes Ink to leave the terminal in a half-raw state
2	setEncoding("utf8") never reset	This is a sticky, one-way call on the Node.js public API. Once set, stdin delivers strings instead of Buffers to all subsequent consumers, breaking Claude's input handling
3	process.exit() bypasses finally blocks	Signal handlers (SIGINT/SIGTERM) call process.exit() which skips the finally block that would restore the terminal — leaves it in raw mode
4	No signal forwarding to binary children	When spawning Claude as a binary (e.g. Homebrew install), the parent process doesn't forward signals — child becomes orphan competing for stdin
5	stdin left in flowing mode	No pause() after remote cleanup, so stdin data events keep firing into the void

Approach: why this fix over alternatives

Compared to PR #458 (pkill-based process cleanup)

PR #458 addresses the orphan process symptom by adding HAPPY_SESSION_ID environment tracking and pkill-based cleanup with escalating SIGTERM→SIGKILL. While it correctly identifies the orphan problem, it:

• Doesn't fix the core stdin corruption (bugs 1-3 above) — the wrong cleanup order, sticky encoding, and signal handler gaps
• Adds pkill -f "HAPPY_SESSION_ID=..." with hardcoded timeouts (100ms → 500ms) which is platform-dependent and fragile
• Registers signal handlers 4+ times ("multiple times to ensure they stick") which is a code smell
• Adds a raw mode toggle hack in RemoteModeDisplay.tsx with setTimeout(100ms) that papers over the real ordering bug

Compared to PR #553 (node-pty proxy)

PR #553 takes a nuclear approach: replace stdio: 'inherit' with a full PTY proxy via node-pty, giving Ink a separate /dev/tty fd. This correctly isolates stdin but:

• Adds a native dependency (node-pty) requiring compilation on every platform — the comment thread already found a PTY fd leak bug in node-pty v1.1.0 (fix: /dev/ptmx leak on macOS microsoft/node-pty#882)
• Rewrites 200+ lines of claudeLocal.ts including IPC socket plumbing to replace fd 3
• Much larger blast radius and review surface for what is fundamentally a cleanup ordering bug

This PR's approach

Minimal, targeted fixes at each root cause — 94 lines added, 8 removed, zero new dependencies:

1. restoreStdin() utility (new file) — idempotent function that properly restores stdin: disable raw mode, pause, reset encoding via _readableState, remove orphaned listeners. Every operation wrapped in try-catch.

2. Fix cleanup order in claudeRemoteLauncher.ts — unmount Ink first (while raw mode is still active), then call restoreStdin(). This is the core fix. Also removed dead code (process.stdin.off('data', abort) where abort was never a data listener).

3. Defensive guard in claudeLocal.ts — call restoreStdin() before spawning child with inherited stdio. Catches edge cases where remote cleanup was incomplete.

4. Signal handler protection in runClaude.ts — call restoreStdin() at the top of the cleanup function, before any async work or process.exit(). Prevents terminal being left in raw mode when signals bypass finally blocks.

5. Signal forwarding in claude_version_utils.cjs — forward SIGINT/SIGTERM/SIGHUP to binary child processes. Clean up handlers on child exit. Prevents orphan Claude processes.

Files changed

File	Lines	Change
packages/happy-cli/src/utils/restoreStdin.ts	+53	New — shared stdin restoration utility
packages/happy-cli/src/claude/claudeRemoteLauncher.ts	+12/-6	Fix cleanup order, use restoreStdin()
packages/happy-cli/src/claude/claudeLocal.ts	+5/-2	Defensive restoreStdin() before spawn
packages/happy-cli/src/claude/runClaude.ts	+6	restoreStdin() in signal handler
packages/happy-cli/scripts/claude_version_utils.cjs	+18	Signal forwarding to binary children

Test plan

• TypeScript type check passes (tsc --noEmit)
• Full build passes (yarn build)
• All 273 existing tests pass (vitest run)
• Manual: Start happy → send message from mobile (enter remote mode) → double-space to switch to local → type a sentence with spaces → verify all characters appear, no phantom mode switches
• Manual: Ctrl-C twice in remote mode → restart → verify terminal is clean
• Manual: Rapid switching: remote→local→remote→local
• Manual: ps aux | grep claude after mode switches — verify no orphan processes
• Manual: Test on both macOS and Linux

Generated with Claude Code
via Happy

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0b9a99171b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Forward all repeated termination signals to child

child.killed becomes true as soon as the first kill() is sent, not when the child has actually exited, so this guard drops every later signal even if the child is still running. In binary-install flows, if Claude traps the first signal (for graceful interrupt) and keeps running, a subsequent SIGTERM from a mode switch or shutdown will never be forwarded, which can leave the launcher waiting indefinitely for exit while the child continues owning stdin.

Useful? React with 👍 / 👎.

[leave-a-message]

Hit this twice on macOS (M1). Had to kill the terminal both times to recover. Would love to see this land — thanks for the fix @tomstetson.