fix(tui): survive dead terminal during shutdown

Author: code-yeongyu

packages/tui/src/changes.md

@@ -1,5 +1,32 @@
 # TUI delta rendering fork changes
 
+## 2026-08-05: dead-terminal raw-mode restoration is best-effort during shutdown
+
+### What changed
+
+- `ProcessTerminal.stop()` still restores the raw-mode state captured by `start()`, but now treats `EIO`, `EPIPE`,
+  and `ENOTCONN` from the teardown-time `setRawMode()` call as a dead terminal instead of crashing the exiting CLI.
+- Unexpected raw-mode restoration errors still propagate so shutdown does not hide unrelated defects.
+- `test/terminal.test.ts` covers successful restoration, the dead-terminal `EIO` regression, and unexpected-error
+  propagation.
+
+### Why
+
+- An SSH or PTY peer can disappear after input draining but before raw-mode restoration. Node/Bun then throws a
+  synchronous stdin ioctl error, which bypasses the coding-agent's stdout/stderr error handlers and replaces the
+  requested exit with an uncaught `setRawMode failed with errno: 5` stack.
+
+### Why this cannot be expressed externally
+
+- Raw-mode ownership and restoration are private `ProcessTerminal` lifecycle responsibilities. Extensions receive
+  neither the saved raw-mode state nor a teardown hook around the stdin ioctl.
+
+### Expected merge conflict zones
+
+- LOW: `packages/tui/src/terminal.ts` around the terminal error classifier and `ProcessTerminal.stop()` raw-mode
+  restoration.
+- LOW: `packages/tui/test/terminal.test.ts` around lifecycle coverage.
+
 ## 2026-07-31: atomic visible-cursor frames for IME and animations
 
 ### What changed

packages/tui/src/terminal.ts

@@ -13,6 +13,7 @@ const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
 const APPLE_TERMINAL_SHIFT_ENTER_SEQUENCE = "\x1b[13;2u";
 const DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS = 7;
+const DEAD_TERMINAL_ERROR_CODES = new Set(["EIO", "EPIPE", "ENOTCONN"]);
 const KEYBOARD_PROTOCOL_RESPONSE_FRAGMENT_TIMEOUT_MS = 150;
 const KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1b[>${DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS}u\x1b[?u\x1b[c`;
 
@@ -52,6 +53,15 @@ export function keyboardEnhancementEnabled(): boolean {
 	return !["0", "false", "no", "off"].includes(value.toLowerCase());
 }
 
+function isDeadTerminalError(error: unknown): boolean {
+	return (
+		error instanceof Error &&
+		"code" in error &&
+		typeof error.code === "string" &&
+		DEAD_TERMINAL_ERROR_CODES.has(error.code)
+	);
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -529,7 +539,11 @@ export class ProcessTerminal implements Terminal {
 
 		// Restore raw mode state
 		if (process.stdin.setRawMode) {
-			process.stdin.setRawMode(this.wasRaw);
+			try {
+				process.stdin.setRawMode(this.wasRaw);
+			} catch (error) {
+				if (!isDeadTerminalError(error)) throw error;
+			}
 		}
 
 		this.removeExternalStdoutGuard();

packages/tui/test/terminal.test.ts

@@ -47,6 +47,33 @@ function resetFakeTimers(): void {
 	mock.timers.reset();
 }
 
+type TerminalStopHarness = {
+	terminal: ProcessTerminal;
+	cleanup(): void;
+};
+
+function setupTerminalStopHarness(wasRaw: boolean, restoreRawMode: (mode: boolean) => void): TerminalStopHarness {
+	const terminal = new ProcessTerminal();
+	const previousPause = process.stdin.pause;
+	const previousSetRawMode = process.stdin.setRawMode;
+
+	Reflect.set(terminal, "wasRaw", wasRaw);
+	Reflect.set(terminal, "rawStdoutWrite", (_data: string) => {});
+	Reflect.set(process.stdin, "pause", () => process.stdin);
+	Reflect.set(process.stdin, "setRawMode", (mode: boolean) => {
+		restoreRawMode(mode);
+		return process.stdin;
+	});
+
+	return {
+		terminal,
+		cleanup(): void {
+			Reflect.set(process.stdin, "pause", previousPause);
+			Reflect.set(process.stdin, "setRawMode", previousSetRawMode);
+		},
+	};
+}
+
 describe("normalizeAppleTerminalInput", () => {
 	it("rewrites Apple Terminal Return to CSI-u Shift+Enter when Shift is pressed", () => {
 		assert.equal(normalizeAppleTerminalInput("\r", true, true), "\x1b[13;2u");
@@ -295,6 +322,59 @@ describe("ProcessTerminal Kitty keyboard protocol negotiation", () => {
 	});
 });
 
+describe("ProcessTerminal stop", () => {
+	it("restores the previous raw mode during stop", () => {
+		// Given
+		const restoredModes: boolean[] = [];
+		const harness = setupTerminalStopHarness(true, (mode) => {
+			restoredModes.push(mode);
+		});
+
+		try {
+			// When
+			harness.terminal.stop();
+
+			// Then
+			assert.deepEqual(restoredModes, [true]);
+		} finally {
+			harness.cleanup();
+		}
+	});
+
+	it("does not throw when raw-mode restoration fails during stop", () => {
+		// Given
+		const eio = Object.assign(new Error("setRawMode failed"), { code: "EIO" });
+		const harness = setupTerminalStopHarness(false, () => {
+			throw eio;
+		});
+
+		try {
+			// When / Then
+			assert.doesNotThrow(() => harness.terminal.stop());
+		} finally {
+			harness.cleanup();
+		}
+	});
+
+	it("rethrows unexpected raw-mode restoration failures", () => {
+		// Given
+		const invalidArgument = Object.assign(new Error("unexpected setRawMode failure"), { code: "EINVAL" });
+		const harness = setupTerminalStopHarness(false, () => {
+			throw invalidArgument;
+		});
+
+		try {
+			// When / Then
+			assert.throws(
+				() => harness.terminal.stop(),
+				(error: unknown) => error === invalidArgument,
+			);
+		} finally {
+			harness.cleanup();
+		}
+	});
+});
+
 describe("ProcessTerminal dimensions", () => {
 	it("falls back to COLUMNS and LINES before default dimensions", () => {
 		const previousColumnsDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "columns");