feat(tui): let a queued decision gate preempt a command surface

Allow-once settles exactly once and frees the single-slot overlay host, so an already-queued or newly raised card paints before any deferred slash/settings/MCP surface. Command surfaces suspend and return after the gate settles; inline popups keep their stacking contracts.

Author: TheGreatAxios

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

@@ -28,10 +28,7 @@ import type {
   PermissionRequest,
 } from "../permission/types.js";
 import { defined } from "../../tests/helpers/defined.js";
-import {
-  attachSessionBridge,
-  createRecordingPort,
-} from "./runtime-bridge.js";
+import { attachSessionBridge, createRecordingPort } from "./runtime-bridge.js";
 import { withTestRenderer } from "./harness.js";
 import { createAppShell } from "./shell/index.js";
 import type { AppShell } from "./shell/internals.js";
@@ -83,6 +80,18 @@ async function settledWithin<T>(
   }
 }
 
+/**
+ * `gate.evaluate()` raises its card asynchronously (decide → approval seam →
+ * emit → enqueue), so the overlay is never up on the very next line. Flush
+ * macrotasks so the card is raised — shown, or queued behind the live gate —
+ * before asserting on the host. All gate-side work is microtasks, so two
+ * macrotask drains provably suffice; nothing here changes what is asserted.
+ */
+async function flushGateRaise(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 async function withWiredWorld(
   run: (world: {
     shell: AppShell;
@@ -138,6 +147,7 @@ describe("CL-8792 gate level: a second destructive evaluation re-prompts after a
     await withWiredWorld(async ({ shell, emitter }) => {
       const gate = createOverlayBackedGate(emitter);
       const first = gate.evaluate(shellCall("rm -rf /tmp/cl8792-a"));
+      await flushGateRaise();
       expect(shell.overlayKind).toBe("permissions");
 
       acceptChoice(shell, 1);
@@ -147,6 +157,7 @@ describe("CL-8792 gate level: a second destructive evaluation re-prompts after a
       expect(firstVerdict.value.allowed).toBe(true);
 
       const second = gate.evaluate(shellCall("rm -rf /tmp/cl8792-b"));
+      await flushGateRaise();
       // Allow-once persisted nothing, so the new command must prompt again.
       expect(shell.overlayKind).toBe("permissions");
       acceptChoice(shell, 1);
@@ -162,11 +173,13 @@ describe("CL-8792 gate level: a second destructive evaluation re-prompts after a
       const gate = createOverlayBackedGate(emitter);
       const command = "rm -rf /tmp/cl8792-same";
       const first = gate.evaluate(shellCall(command));
+      await flushGateRaise();
       expect(shell.overlayKind).toBe("permissions");
       acceptChoice(shell, 1);
       await settledWithin(first, 500);
 
       const second = gate.evaluate(shellCall(command));
+      await flushGateRaise();
       // A grant would auto-allow with no overlay; allow-once must re-prompt.
       expect(shell.overlayKind).toBe("permissions");
       acceptChoice(shell, 1);
@@ -181,13 +194,16 @@ describe("CL-8792 gate level: a second destructive evaluation re-prompts after a
     await withWiredWorld(async ({ shell, emitter }) => {
       const gate = createOverlayBackedGate(emitter);
       const first = gate.evaluate(shellCall("rm -rf /tmp/cl8792-a"));
+      await flushGateRaise();
       expect(shell.overlayKind).toBe("permissions");
 
       // A slash opened under the live gate defers; the live gate keeps it waiting.
       openSlash(shell);
       expect(shell.overlayKind).toBe("permissions");
 
       const second = gate.evaluate(shellCall("rm -rf /tmp/cl8792-b"));
+      // Let the second card enqueue behind the live gate before accepting it.
+      await flushGateRaise();
 
       // Accept once on the first card: the queued card must take the host
       // before the deferred slash, and both evaluations must settle.
@@ -305,7 +321,10 @@ describe("CL-8792 overlay host: queued cards outrank deferred surfaces", () => {
       });
 
       acceptChoice(shell, 2);
-      expect(resolvedA).toMatchObject({ allow: true, persist: { id: "scope-a" } });
+      expect(resolvedA).toMatchObject({
+        allow: true,
+        persist: { id: "scope-a" },
+      });
       expect(shell.overlayKind).toBe("permissions");
 
       acceptChoice(shell, 1);

src/tui/gate-wire.ts

@@ -19,7 +19,9 @@ import {
   closeInsetOverlay,
   isOverlayHostIdle,
   onOverlayClosed,
+  resumeSuspendedCommandSurface,
   setOverlayBody,
+  suspendReplaceableOverlay,
 } from "./shell/overlay-host.js";
 import { EXPAND_KEY } from "./stream.js";
 import {
@@ -258,6 +260,7 @@ export function wireGates(
   // nothing on screen to answer — so a gate that arrives while another overlay
   // is up waits here and opens as soon as the host frees up.
   const pending: (() => void)[] = [];
+  let disposed = false;
   // Owns queued-approval reconciliation (see src/permission/queue.ts): this
   // host only enqueues requests and renders whatever settle calls the queue
   // hands back — it never decides which grant covers which request.
@@ -295,11 +298,45 @@ export function wireGates(
   }
 
   function openOrQueue(open: () => void): void {
-    if (!isOverlayHostIdle(shell)) {
+    if (isOverlayHostIdle(shell)) {
+      openHost(open);
+      return;
+    }
+    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.
       pending.push(open);
+      suspendReplaceableOverlay(shell);
+      // The suspend-close's idle-notify may already have opened an older
+      // queued gate (FIFO): drain here only if the host is still free, so a
+      // close-notify drain is never doubled.
+      if (shell.overlayList === null) {
+        const next = pending.shift();
+        if (next !== undefined) openHost(next);
+      }
+      return;
+    }
+    pending.push(open);
+  }
+
+  /**
+   * Open the next queued gate, else return a suspended command surface to
+   * the host. Every gate settle path runs this after resolving. Skipped past
+   * teardown so a late settle cannot paint onto a dead shell.
+   */
+  function drainPendingOrResume(): void {
+    if (disposed || shell.disposed) return;
+    // A close-notify drain may already have taken the host (Esc / timeout
+    // while displayed): never double-open, and never tear down a live gate.
+    if (shell.overlayList !== null) return;
+    const next = pending.shift();
+    if (next !== undefined) {
+      openHost(next);
       return;
     }
-    openHost(open);
+    resumeSuspendedCommandSurface(shell);
   }
 
   function unqueue(open: () => void): void {
@@ -351,6 +388,9 @@ export function wireGates(
         closeInsetOverlay(shell);
       }
       resolve(outcome);
+      // The next queued gate takes the host before any deferred surface;
+      // a suspended command surface returns only when no gate is waiting.
+      drainPendingOrResume();
     });
 
     const onToggleExpand = (): void => {
@@ -496,11 +536,7 @@ export function wireGates(
         // ask — or the overlay's generic accept echo — into the transcript.
         echoChoice: false,
         onAccept: (sel: OverlaySelection) => {
-          if (settled) return;
-          settled = true;
-          clearTimers();
-          operatorTeardowns.delete(teardown);
-          resolve(
+          settleOnce(
             operatorResultFromSelection(choices, {
               index: sel.index,
               ...(sel.id !== undefined ? { id: sel.id } : {}),
@@ -510,11 +546,7 @@ export function wireGates(
         // The ask_operator contract offers a free-form answer, so the overlay
         // must be able to send one back rather than only an option index.
         onTextAnswer: (text: string) => {
-          if (settled) return;
-          settled = true;
-          clearTimers();
-          operatorTeardowns.delete(teardown);
-          resolve(operatorCustomResult(text));
+          settleOnce(operatorCustomResult(text));
         },
         // Esc must settle the awaited promise (as a cancel), not abandon it —
         // an unresolved gate hangs the run until the process is killed.
@@ -523,11 +555,7 @@ export function wireGates(
         // closeInsetOverlay itself; doing so would reenter this same
         // onCancel (see the permission gate's identical note on `settle`).
         onCancel: () => {
-          if (settled) return;
-          settled = true;
-          clearTimers();
-          operatorTeardowns.delete(teardown);
-          resolve(operatorCancelResult());
+          settleOnce(operatorCancelResult());
         },
         isGate: true,
       });
@@ -544,6 +572,9 @@ export function wireGates(
         closeInsetOverlay(shell);
       }
       resolve(result);
+      // The next queued gate takes the host before any deferred surface;
+      // a suspended command surface returns only when no gate is waiting.
+      drainPendingOrResume();
     };
     const autoCancel = (): void => {
       settleOnce(operatorCancelResult());
@@ -568,6 +599,7 @@ export function wireGates(
   emitter.on("operator.gate", onOperator);
 
   return () => {
+    disposed = true;
     emitter.off("permission.gate", onPermission);
     emitter.off("operator.gate", onOperator);
     disposeReconciliation();

src/tui/runtime-bridge.ts

@@ -30,6 +30,7 @@ import {
 import {
   clearShellBridgeHooks,
   setShellBridgeHooks,
+  shellInternals,
   type AppShell,
 } from "./shell/internals.js";
 import { applyShellInterrupt, surfaceSystemNotice } from "./shell/prompt.js";
@@ -1185,10 +1186,18 @@ function syncShellOutputs(
 /**
  * Refresh every plain in-flight tool call's row with how long it has been
  * running, frame-coalesced. `spawn_agent` dispatches already get this (and
- * more) from `syncAgentProgress`, so they are skipped here.
+ * more) from `syncAgentProgress`, so they are skipped here. While a decision
+ * gate is outstanding but not on screen — queued behind another overlay — the
+ * tool waits on an operator who cannot see it yet, so its elapsed stays frozen
+ * and the row reads as paused instead of running. Once the gate is shown the
+ * clock runs again: the operator can see what blocks the tool.
  */
 function syncToolElapsed(shell: AppShell, bag: BridgeBag, nowMs: number): void {
   if (bag.toolCallStartedAt.size === 0) return;
+  const gateOnScreen =
+    shell.overlayList !== null &&
+    shellInternals(shell)?.primaryBindings.isGate === true;
+  const gateHidden = bag.turn.blockedGateCount > 0 && !gateOnScreen;
   for (const [callId, startedAt] of bag.toolCallStartedAt) {
     if (bag.taskCallIds.has(callId)) continue;
     const index = bag.toolRows.get(callId);
@@ -1201,6 +1210,7 @@ function syncToolElapsed(shell: AppShell, bag: BridgeBag, nowMs: number): void {
       bag.toolCallStartedAt.delete(callId);
       continue;
     }
+    if (gateHidden) continue;
     const current = bag.pendingRowUpdates.get(index) ?? row;
     const stat = clockLabel(nowMs - startedAt);
     if (current.stat === stat) continue;

src/tui/shell/index.ts

@@ -523,6 +523,7 @@ export function createAppShell(
     overlayClosedListeners: new Set(),
     deferredCommandOverlay: null,
     deferredFlushScheduled: false,
+    suspendedCommandSurface: null,
     overlayHostReservations: 0,
     overlayReservationEpoch: 0,
     paletteCatalog: paletteCatalogOpt,

src/tui/shell/internals.ts

@@ -684,7 +684,7 @@ export const EMPTY_PRIMARY_BINDINGS: Readonly<PrimaryOverlayBindings> = {
   mcpAddHint: false,
 };
 
-interface PriorOverlaySnapshot {
+export interface PriorOverlaySnapshot {
   readonly kind: PrimaryOverlayKind | null;
   readonly items: readonly string[];
   readonly bodyLines: readonly string[];
@@ -711,6 +711,13 @@ interface ShellInternals {
   overlayRawBodyText: string;
   /** Snapshot when palette stacks over another primary overlay. */
   priorOverlay: PriorOverlaySnapshot | null;
+  /**
+   * Replaceable command surface suspended while a decision gate holds the
+   * host. One slot; restored after the gate settles when no queued gate
+   * takes the host first. Never a gate or palette — those keep their own
+   * stacking contracts.
+   */
+  suspendedCommandSurface: PriorOverlaySnapshot | null;
   /** Advances on a new overlay taking the host, and when the host empties. */
   overlayGeneration: number;
   primaryBindings: PrimaryOverlayBindings;