Restore the terminal on a detached throw before exiting

A throw that escapes runTUI's own try/catch (e.g. inside a
fire-and-forget void call) only reached the top-level
uncaughtException/unhandledRejection handler, which had no way to
call runTUI's terminal-restore routine since it lives as a closure
bound only once the OpenTUI host mounts. The process exited with
the terminal left in the alternate screen and raw mode still on.

A module-level slot mirroring the existing active-run.ts pattern
lets the handler reach it.

Author: TheGreatAxios

src/index.ts

@@ -2,6 +2,7 @@ import { getLogger } from "@intx/log";
 import { LOG_NAMESPACE_ROOT } from "./branding.js";
 import { primeCrashReporting, writeCrashReport, type CrashKind } from "./crash/report.js";
 import { getActiveRun, markCrashed } from "./session/active-run.js";
+import { getActiveDisposeHost } from "./session/active-host.js";
 import { saveCrashState } from "./session/state.js";
 import { loadConfig } from "./config/index.js";
 import { ensureTelemetrySettings, globalSettingsPath } from "./config/settings.js";
@@ -115,9 +116,30 @@ export async function main(argv: readonly string[]): Promise<number> {
   });
 }
 
+// Shared by handleFatal and the signal handlers below so a signal arriving
+// mid-crash-unwind (or a crash surfacing while a signal is already tearing
+// the process down) can't re-enter either path a second time.
+let terminating = false;
+
 // Exported so an integration test can register these process-level handlers
 // and inject a crash without spawning the full TUI stack.
 export async function handleFatal(kind: CrashKind, error: unknown): Promise<void> {
+  if (terminating) return;
+  terminating = true;
+  // OpenTUI's own uncaughtException/unhandledRejection listener only logs
+  // (see installCrashHandlers' comment below) — it never tears down the
+  // terminal the way its signal listener does. Without this, a throw that
+  // escapes runTUI's own try/catch (e.g. inside a fire-and-forget `void`
+  // call) leaves the alternate screen and raw mode stuck. disposeHost is
+  // idempotent, so this is safe even if runTUI's own catch block already
+  // ran it moments earlier.
+  try {
+    getActiveDisposeHost()?.();
+  } catch (disposeErr: unknown) {
+    process.stderr.write(
+      `host dispose failed during fatal handling: ${disposeErr instanceof Error ? disposeErr.message : String(disposeErr)}\n`,
+    );
+  }
   // Flip this before any awaits below so any snapshot write still queued
   // behind another one in state.ts's per-session chain sees it and steps
   // aside the moment it's next in line, rather than racing saveCrashState's

src/session/active-host.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { clearActiveDisposeHost, getActiveDisposeHost, setActiveDisposeHost } from "./active-host.js";
+
+describe("active-host", () => {
+  afterEach(() => {
+    clearActiveDisposeHost();
+  });
+
+  test("starts with no active dispose handle", () => {
+    expect(getActiveDisposeHost()).toBeNull();
+  });
+
+  test("returns the handle set by setActiveDisposeHost", () => {
+    const disposeHost = () => {};
+    setActiveDisposeHost(disposeHost);
+    expect(getActiveDisposeHost()).toBe(disposeHost);
+  });
+
+  test("clearActiveDisposeHost removes the handle", () => {
+    setActiveDisposeHost(() => {});
+    clearActiveDisposeHost();
+    expect(getActiveDisposeHost()).toBeNull();
+  });
+
+  test("setActiveDisposeHost overwrites a previously set handle", () => {
+    setActiveDisposeHost(() => {});
+    const second = () => {};
+    setActiveDisposeHost(second);
+    expect(getActiveDisposeHost()).toBe(second);
+  });
+});

src/session/active-host.ts

@@ -0,0 +1,20 @@
+// A module-level slot mirroring active-run.ts's pattern: the top-level
+// process handlers in src/index.ts (a detached-throw handler today, a signal
+// handler alongside it) need to reach runTUI's terminal-restore routine even
+// though it is a closure local to runTUI, bound only once the OpenTUI host
+// has mounted. Cleared the moment runTUI itself finalizes (normally or via
+// its own crash path) so a signal arriving after teardown has nothing left
+// to call.
+let activeDisposeHost: (() => void) | null = null;
+
+export function setActiveDisposeHost(disposeHost: () => void): void {
+  activeDisposeHost = disposeHost;
+}
+
+export function clearActiveDisposeHost(): void {
+  activeDisposeHost = null;
+}
+
+export function getActiveDisposeHost(): (() => void) | null {
+  return activeDisposeHost;
+}

src/tui/runner.ts

@@ -167,6 +167,7 @@ import { generateSessionId, initSessionDir, renameSession, sessionContextDir, se
 import { resolveSessionLabel, truncateSessionLabel } from "../session/session-label.js";
 import { loadState, saveState, type ConnectedMcpServer, type RunState } from "../session/state.js";
 import { setActiveRun, clearActiveRun, type RunStateHandle } from "../session/active-run.js";
+import { setActiveDisposeHost, clearActiveDisposeHost } from "../session/active-host.js";
 import { openInBrowser } from "../auth/oauth/browser.js";
 import { pickSession } from "./pick-session.js";
 import { RESUME_TRANSCRIPT_BLOCK_LIMIT, turnsToContentBlocks } from "./turns-to-blocks.js";
@@ -529,6 +530,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
     finalized = true;
     activeRunHandle.active = false;
     clearActiveRun();
+    clearActiveDisposeHost();
     await flushPartialOnCrash().catch((flushErr: unknown) => {
       // Best-effort only — still attempt saveState below. Log so a flush
       // failure is not invisible when diagnosing a crash exit.
@@ -2192,6 +2194,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   });
 
   disposeHost = host.dispose;
+  setActiveDisposeHost(disposeHost);
 
   setMentionSuggestionSource(host.shell, (prefix) => listPathSuggestions(prefix, config.cwd));
 
@@ -2296,6 +2299,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   finalized = true;
   activeRunHandle.active = false;
   clearActiveRun();
+  clearActiveDisposeHost();
   await writeRunSnapshot(persistedStatus, {
     finishedAt,
     ...(sinkError !== undefined ? { error: sinkError } : {}),