fix(tui): keep suspended overlays live when a gate preempts them

Suspend was a dismiss: it ran onCancel/onDispose and destroyed the
list, so restore painted a dead widget and MCP could steal the host
from the arriving gate. The preemptable-kind set also used command
aliases, so /model and /connect never yielded.

Author: TheGreatAxios

src/tui/allow-once-reprompt.test.ts

@@ -34,13 +34,15 @@ import { createAppShell } from "./shell/index.js";
 import type { AppShell } from "./shell/internals.js";
 import {
   acceptOverlaySelection,
+  closeInsetOverlay,
   openListOverlay,
 } from "./shell/overlay-host.js";
 import { moveOverlaySelection } from "./shell/overlay-list.js";
 import { streamRowCount } from "./shell/transcript.js";
 import { wireGates } from "./gate-wire.js";
 import type { PermissionGateEvent } from "./gate-events.js";
 import { createGateRequestApproval } from "./request-approval.js";
+import { openAddProviderOverlay, openModelPickerOverlay } from "./overlays.js";
 
 const shellCall = (command: string): ToolCall => ({
   id: "c",
@@ -475,3 +477,148 @@ describe("CL-8792 elapsed: pending tool row freezes while a gate is outstanding
     );
   });
 });
+
+describe("CL-8792 overlay host: suspend preserves the surface instead of dismissing it", () => {
+  test("suspend does not fire onCancel or onDispose", async () => {
+    await withWiredWorld(async ({ shell, emitter }) => {
+      const events: string[] = [];
+      openListOverlay(shell, {
+        kind: "help",
+        title: "Slash",
+        items: ["Help"],
+        onCancel: () => events.push("cancel"),
+        onDispose: () => events.push("dispose"),
+      });
+      expect(shell.overlayKind).toBe("help");
+
+      let resolved: unknown;
+      emitter.emit("permission.gate", {
+        id: "req-suspend-hooks",
+        request: destructiveRequest("rm -rf /tmp/cl8792-suspend-hooks"),
+        resolve: (outcome: unknown) => {
+          resolved = outcome;
+        },
+      });
+      expect(shell.overlayKind).toBe("permissions");
+      expect(events).toEqual([]);
+
+      acceptChoice(shell, 1);
+      expect(resolved).toEqual({ allow: true });
+      expect(shell.overlayKind).toBe("help");
+      expect(events).toEqual([]);
+
+      closeInsetOverlay(shell);
+      expect(events).toEqual(["dispose", "cancel"]);
+    });
+  });
+
+  test("restored SelectRenderable is live and parented in overlayView.body", async () => {
+    await withWiredWorld(async ({ shell, emitter }) => {
+      openSlash(shell);
+      const list = defined(shell.overlayList, "slash list");
+      expect(list.select.isDestroyed).toBe(false);
+      expect(list.select.parent).toBe(shell.overlayView.body);
+
+      let resolved: unknown;
+      emitter.emit("permission.gate", {
+        id: "req-restore-list",
+        request: destructiveRequest("rm -rf /tmp/cl8792-restore-list"),
+        resolve: (outcome: unknown) => {
+          resolved = outcome;
+        },
+      });
+      expect(shell.overlayKind).toBe("permissions");
+
+      acceptChoice(shell, 1);
+      expect(resolved).toEqual({ allow: true });
+      expect(shell.overlayKind).toBe("help");
+      expect(shell.overlayList).toBe(list);
+      expect(list.select.isDestroyed).toBe(false);
+      expect(list.select.parent).toBe(shell.overlayView.body);
+      expect(shell.overlayView.body.getChildren()).toContain(list.select);
+    });
+  });
+
+  test.each([
+    {
+      kind: "model_picker" as const,
+      open: (shell: AppShell) =>
+        openModelPickerOverlay(shell, { items: ["grok-3"] }),
+    },
+    {
+      kind: "add_provider" as const,
+      open: (shell: AppShell) =>
+        openAddProviderOverlay(shell, {
+          items: ["custom"],
+          itemIds: ["custom"],
+        }),
+    },
+  ])(
+    "$kind yields to a newly raised gate and returns after settle",
+    async ({ kind, open }) => {
+      await withWiredWorld(async ({ shell, emitter }) => {
+        open(shell);
+        expect(shell.overlayKind).toBe(kind);
+
+        let resolved: unknown;
+        emitter.emit("permission.gate", {
+          id: `req-yield-${kind}`,
+          request: destructiveRequest(`rm -rf /tmp/cl8792-yield-${kind}`),
+          resolve: (outcome: unknown) => {
+            resolved = outcome;
+          },
+        });
+        expect(shell.overlayKind).toBe("permissions");
+
+        acceptChoice(shell, 1);
+        expect(resolved).toEqual({ allow: true });
+        expect(shell.overlayKind).toBe(kind);
+      });
+    },
+  );
+
+  test("MCP onCancel during suspend does not steal the host from a queued gate while a deferred slash occupies idle", async () => {
+    await withWiredWorld(async ({ shell, emitter }) => {
+      let cancelOpens = 0;
+      openListOverlay(shell, {
+        kind: "mcp",
+        title: `remove stolen`,
+        items: ["Remove stolen", "Cancel"],
+        onCancel: () => {
+          cancelOpens += 1;
+          openListOverlay(shell, {
+            kind: "mcp",
+            title: "mcp",
+            items: ["stolen-server"],
+          });
+        },
+      });
+      expect(shell.overlayKind).toBe("mcp");
+
+      openSlash(shell);
+      expect(shell.overlayKind).toBe("mcp");
+
+      let resolved: unknown;
+      emitter.emit("permission.gate", {
+        id: "req-mcp-cancel-steal",
+        request: destructiveRequest("rm -rf /tmp/cl8792-mcp-steal"),
+        resolve: (outcome: unknown) => {
+          resolved = outcome;
+        },
+      });
+      expect(cancelOpens).toBe(0);
+      expect(shell.overlayKind).toBe("permissions");
+      expect(shell.overlayItems).toContain("Accept once");
+
+      acceptChoice(shell, 1);
+      expect(resolved).toEqual({ allow: true });
+      expect(cancelOpens).toBe(0);
+      expect(shell.overlayKind).toBe("mcp");
+      expect(shell.overlayItems).toEqual(["Remove stolen", "Cancel"]);
+
+      await Promise.resolve();
+      expect(shell.overlayKind).toBe("mcp");
+      expect(shell.overlayItems).not.toEqual(["Help"]);
+    });
+  });
+});

src/tui/gate-wire.ts

@@ -305,8 +305,8 @@ export function wireGates(
     if (shell.overlayList !== null) {
       // A replaceable command surface yields to the decision gate and is
       // restored after the gate settles. The suspend is a no-op for live
-      // gates and non-surface popups (palette, mentions, pickers — they keep
-      // their stacking contracts), so those arrivals simply stay queued.
+      // gates and stacked popups (palette, mentions — they keep their
+      // stacking contracts), so those arrivals simply stay queued.
       pending.push(open);
       suspendReplaceableOverlay(shell);
       // The suspend-close's idle-notify may already have opened an older

src/tui/overlay-view.ts

@@ -435,5 +435,5 @@ export function createOverlayView(ctx: RenderContext) {
     );
   }
 
-  return { host, title, body, paintTitle, paintList, clearBody };
+  return { host, title, body, paintTitle, paintList, clearBody, detachList };
 }

src/tui/shell/overlay-host.ts

@@ -174,28 +174,32 @@ function restorePrimaryFrame(
 }
 
 /**
- * Kinds opened through `openCommandSurface` (`CommandSurfaceKind` in
- * ../command-surfaces.ts, restated here to keep shell/ import-clean). Only
- * these yield to a decision gate. Inline popups (mentions, palette, pickers)
- * keep their stacking contracts — suspending one would strand its owner, the
- * CL-6698 mention-refresh stall — so a gate arriving behind them stays queued.
+ * Command surfaces that occupy the shared host and can yield to a decision
+ * gate. Kinds are the live `PrimaryOverlayKind` values those surfaces open
+ * with (`model_picker` / `add_provider`, not the command-surface aliases
+ * `models` / `add-provider`). Inline popups (mentions, palette, pickers that
+ * stack) keep their stacking contracts — suspending one would strand its
+ * owner, the CL-6698 mention-refresh stall — so a gate arriving behind them
+ * stays queued.
  */
-const GATE_PREEMPTABLE_SURFACE_KINDS: ReadonlySet<string> = new Set([
-  "help",
-  "settings",
-  "permissions",
-  "plugins",
-  "hooks",
-  "mcp",
-  "models",
-  "add-provider",
-]);
+const GATE_PREEMPTABLE_SURFACE_KINDS: ReadonlySet<PrimaryOverlayKind> = new Set(
+  [
+    "help",
+    "settings",
+    "permissions",
+    "plugins",
+    "hooks",
+    "mcp",
+    "model_picker",
+    "add_provider",
+  ],
+);
 
 /**
  * Suspend the live replaceable command surface so a decision gate can take
  * the host; the surface returns after the gate settles (see
- * `resumeSuspendedCommandSurface`). Live gates and non-surface popups
- * (palette, mentions, pickers) keep their contracts: arrivals behind them
+ * `resumeSuspendedCommandSurface`). Live gates and stacked popups
+ * (palette, mentions) keep their contracts: arrivals behind them
  * stay queued. Never loses a surface: a second suspend is a no-op while one
  * is held.
  */
@@ -209,6 +213,14 @@ export function suspendReplaceableOverlay(shell: AppShell): void {
   const frame = capturePrimaryFrame(shell, bag);
   if (frame === null) return;
   bag.suspendedCommandSurface = frame;
+  // Suspend is not dismiss: keep the captured onCancel/onDispose for restore.
+  // closeInsetOverlay would otherwise run both — MCP's onDispose unsubscribes
+  // without a matching onOpened on restore, and remove-confirm onCancel would
+  // reopen a list onto the empty host and steal it from the arriving gate.
+  bag.primaryBindings.onCancel = null;
+  bag.primaryBindings.onDispose = null;
+  // Restore reuses this SelectRenderable; clearBody would destroy it.
+  shell.overlayView.detachList(frame.list);
   // Unsuspended close: idle-notify lets an older queued gate take the host
   // first (FIFO); the caller opens its gate only if the host is still free.
   closeInsetOverlay(shell);