refactor: clarify restoreTerminalState stdin resume option

src/terminal/restore.test.ts

@@ -58,9 +58,26 @@ describe("restoreTerminalState", () => {
     (process.stdin as { resume?: () => void }).resume = resume;
     (process.stdin as { isPaused?: () => boolean }).isPaused = isPaused;
 
-    restoreTerminalState("test", { resumeStdin: true });
+    restoreTerminalState("test", { resumeStdinIfPaused: true });
 
     expect(setRawMode).toHaveBeenCalledWith(false);
     expect(resume).toHaveBeenCalledOnce();
   });
+
+  it("does not touch stdin when stdin is not a TTY", () => {
+    const setRawMode = vi.fn();
+    const resume = vi.fn();
+    const isPaused = vi.fn(() => true);
+
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
+    (process.stdin as { setRawMode?: (mode: boolean) => void }).setRawMode = setRawMode;
+    (process.stdin as { resume?: () => void }).resume = resume;
+    (process.stdin as { isPaused?: () => boolean }).isPaused = isPaused;
+
+    restoreTerminalState("test", { resumeStdinIfPaused: true });
+
+    expect(setRawMode).not.toHaveBeenCalled();
+    expect(resume).not.toHaveBeenCalled();
+  });
 });

src/terminal/restore.ts

@@ -10,6 +10,13 @@ type RestoreTerminalStateOptions = {
    * Default: false (safer for "cleanup then exit" call sites).
    */
   resumeStdin?: boolean;
+
+  /**
+   * Alias for resumeStdin. Prefer this name to make the behavior explicit.
+   *
+   * Default: false.
+   */
+  resumeStdinIfPaused?: boolean;
 };
 
 function reportRestoreFailure(scope: string, err: unknown, reason?: string): void {
@@ -26,7 +33,9 @@ export function restoreTerminalState(
   reason?: string,
   options: RestoreTerminalStateOptions = {},
 ): void {
-  const resumeStdin = options.resumeStdin ?? false;
+  // Docker TTY note: resuming stdin can keep a container process alive even
+  // after the wizard is "done" (stdin_open: true), making installers appear hung.
+  const resumeStdin = options.resumeStdinIfPaused ?? options.resumeStdin ?? false;
   try {
     clearActiveProgressLine();
   } catch (err) {