Defer overlay idle until slash command dispatch settles

Enter closed the command list before the selected command could claim the host, so a queued permission gate opened in the gap and the command vanished. Idle-notify now waits until dispatch settles, and a live gate is not closed to make room for the command surface.

Author: TheGreatAxios

docs/TUI.md

@@ -256,11 +256,21 @@ for `/status` or an operator question mid-run.
 ## How pop-ups should feel
 
 A blocking surface (permissions, an operator question, the model/provider
-accounting (`src/tui/geometry/resolve.ts`,
+picker, help) occupies the shell's **single overlay host**
+(`src/tui/geometry/resolve.ts`,
 `src/tui/shell.ts:openListOverlay`). Opening a second surface either
 replaces the one that was open or stacks over it; either way Escape always
 walks back along a single path to the prompt.
 
+Accepting a `/` command or palette row keeps that host until dispatch
+settles: the list closes without advertising idle, the command runs, and
+`notifyOverlayClosed` fires only if the host is still empty. A command
+surface (`/help`, `/model`) requested while a live gate still holds the
+host does not steal it and does not silently no-op — it waits until that
+gate closes, with a system line so the wait is visible. A gate that was
+only queued (never shown) stays queued while the command surface is up;
+its display timeout does not run.
+
 An open overlay reserves a real minimum for its own border, title, and at
 least one content row before anything else — including the transcript floor
 — is allowed to starve it further. That minimum is `OVERLAY_MIN_ROWS = 3`
@@ -343,11 +353,18 @@ showing (`repaintPalette`).
 
 `/` at an empty prompt opens the command list, narrowed by name prefix as
 more is typed (`cmd.id` in `openSlashCommands`); Tab completes the name so
-arguments can be typed, Enter runs it. The query lives in the prompt — list
-chrome is in How selectors should work above. When the prefix matches
-nothing, the overlay closes and the prompt is left as typed: `/` then `z`
-with no `z…` command vanishes the list and leaves `/z`. Slash never paints
-a `(no matches)` row. Every entry is backed by the live command registry
+arguments can be typed, Enter runs it. Enter on a matching command keeps
+the overlay host until dispatch settles, so a queued permission gate cannot
+open in the gap between closing the list and opening `/help` or `/model`.
+If the command list is stacked over a live permission or operator prompt,
+that prompt stays; the command surface waits until it closes, and a system
+line says so rather than dropping the selection. Tab, Escape, and Enter
+with no matches are genuine dismisses and still release the host. The query
+lives in the prompt — list chrome is in How selectors should work above.
+When the prefix matches nothing, the list stays open and paints a
+`(no matches)` row (CL-6699: a close-and-reopen refresh would drain a
+queued gate); Enter then dismisses and leaves the prompt as typed (`/z`).
+Every entry is backed by the live command registry
 (`src/tui/command-catalog.ts:commandItemsFromRegistry`) — there is no
 separate palette overlay and no shell-owned action outside the registry. The
 overlay this reuses is still internally called `"palette"` (`shell.ts`'s

src/tui/command-surfaces.ts

@@ -15,10 +15,12 @@ import { residualIdFromSelection, type ResidualCatalogEntry } from "./residuals.
 import {
   captureOverlayContinuation,
   closeInsetOverlay,
+  closeReplaceableOverlay,
   isOverlayContinuationCurrent,
   openHelpOverlay,
   openListOverlay,
   openSettingsOverlay,
+  reserveOverlayHost,
   setOwnedOverlayItems,
   setStatusFlash,
   type AppShell,
@@ -435,8 +437,8 @@ function renderSettingsMenu(
   // against the just-written value; closing first forces a real reopen (a
   // second open of the same primary kind while one is showing is a no-op)
   // while the captured index keeps the cursor where the operator left it.
-  const activeIndex = shell.overlayList?.activeIndex ?? 0;
-  closeInsetOverlay(shell);
+  const activeIndex = shell.overlayKind === "settings" ? (shell.overlayList?.activeIndex ?? 0) : 0;
+  closeReplaceableOverlay(shell);
   const snapshot = settings.read();
   const cycleRows = settingsCycleRows(snapshot, settings);
   const byId = new Map<string, SettingsCycleRow>(cycleRows.map((r) => [r.id, r]));
@@ -506,12 +508,26 @@ export function openSettingsSurface(shell: AppShell, deps: CommandSurfaceDeps):
     renderSettingsMenu(shell, deps, settings, settingsSyncNavRows(deps));
     return;
   }
-  void deps.permissions.list().then((entries) => {
-    renderSettingsMenu(shell, deps, settings, [
-      permissionsNavRow(entries.length),
-      ...settingsSyncNavRows(deps),
-    ]);
-  });
+  const release = reserveOverlayHost(shell);
+  void deps.permissions.list().then(
+    (entries) => {
+      try {
+        renderSettingsMenu(shell, deps, settings, [
+          permissionsNavRow(entries.length),
+          ...settingsSyncNavRows(deps),
+        ]);
+      } finally {
+        release();
+      }
+    },
+    (err: unknown) => {
+      try {
+        deps.notify(`Could not read remembered approvals: ${errorText(err)}`);
+      } finally {
+        release();
+      }
+    },
+  );
 }
 
 /** Remembered approvals; Enter revokes the highlighted grant. */
@@ -521,40 +537,51 @@ export function openPermissionsSurface(shell: AppShell, deps: CommandSurfaceDeps
     deps.notify("Permission administration is not available in this session.");
     return;
   }
+  const release = reserveOverlayHost(shell);
   void permissions.list().then(
     (entries) => {
-      closeInsetOverlay(shell);
-      const rows: ResidualCatalogEntry[] = entries.map((e) => ({
-        id: e.id,
-        label: grantRowLabel(e),
-      }));
-      if (rows.length === 0) {
-        rows.push({
-          id: CLOSE_ID,
-          label: "No remembered approvals — grants you accept appear here",
+      try {
+        closeReplaceableOverlay(shell);
+        const rows: ResidualCatalogEntry[] = entries.map((e) => ({
+          id: e.id,
+          label: grantRowLabel(e),
+        }));
+        if (rows.length === 0) {
+          rows.push({
+            id: CLOSE_ID,
+            label: "No remembered approvals — grants you accept appear here",
+          });
+        }
+        rows.push({ id: BACK_ID, label: "Back to settings" });
+        openListOverlay(shell, {
+          kind: "permissions",
+          title: "permissions · Enter revokes",
+          frameId: "overlay-permissions",
+          ...payload(rows),
+          onAccept: (selection) => {
+            const id = selectedId(selection, rows);
+            if (id === undefined || id === CLOSE_ID) return;
+            if (id === BACK_ID) {
+              openSettingsSurface(shell, deps);
+              return;
+            }
+            void permissions.revoke(id).then(
+              () => openPermissionsSurface(shell, deps),
+              (err: unknown) => deps.notify(`Revoke failed: ${errorText(err)}`),
+            );
+          },
         });
+      } finally {
+        release();
+      }
+    },
+    (err: unknown) => {
+      try {
+        deps.notify(`Could not read remembered approvals: ${errorText(err)}`);
+      } finally {
+        release();
       }
-      rows.push({ id: BACK_ID, label: "Back to settings" });
-      openListOverlay(shell, {
-        kind: "permissions",
-        title: "permissions · Enter revokes",
-        frameId: "overlay-permissions",
-        ...payload(rows),
-        onAccept: (selection) => {
-          const id = selectedId(selection, rows);
-          if (id === undefined || id === CLOSE_ID) return;
-          if (id === BACK_ID) {
-            openSettingsSurface(shell, deps);
-            return;
-          }
-          void permissions.revoke(id).then(
-            () => openPermissionsSurface(shell, deps),
-            (err: unknown) => deps.notify(`Revoke failed: ${errorText(err)}`),
-          );
-        },
-      });
     },
-    (err: unknown) => deps.notify(`Could not read remembered approvals: ${errorText(err)}`),
   );
 }
 
@@ -786,7 +813,7 @@ export function openPluginsSurface(shell: AppShell, deps: CommandSurfaceDeps): v
     deps.notify("Plugin administration is not available in this session.");
     return;
   }
-  closeInsetOverlay(shell);
+  closeReplaceableOverlay(shell);
   const entries = plugins.list();
   const rows: ResidualCatalogEntry[] = entries.map((e) => ({
     id: e.id,
@@ -901,7 +928,7 @@ export function openHooksSurface(shell: AppShell, deps: CommandSurfaceDeps): voi
     deps.notify("Hook administration is not available in this session.");
     return;
   }
-  closeInsetOverlay(shell);
+  closeReplaceableOverlay(shell);
   const entries = hooks.list();
   const rows: ResidualCatalogEntry[] = entries.map((e) => ({ id: e.id, label: hookRowLabel(e) }));
   if (rows.length === 0) {
@@ -1075,7 +1102,7 @@ export function openMcpSurface(
     deps.notify("MCP administration is not available in this session.");
     return;
   }
-  closeInsetOverlay(shell);
+  closeReplaceableOverlay(shell);
   const entries = mcp.list();
   const canAdd = canAddMCPServer(mcp);
   const rows: ResidualCatalogEntry[] = mcpSurfaceRows(entries, canAdd);

src/tui/landing.test.ts

@@ -553,7 +553,7 @@ describe("landing screen", () => {
       try {
         await settle(h);
         const frame = h.captureCharFrame();
-        for (const gone of ["BUSY", "IDLE", "FOLLOW", "queue", "lines", "focus"]) {
+        for (const gone of ["BUSY", "IDLE", "FOLLOW", "follow-up", "lines", "focus"]) {
           expect(frame).not.toContain(gone);
         }
         // The old header blue and status green are gone as fills.