feat(tui): notify the operator when a gate needs attention

Author: TheGreatAxios

src/tui/gate-wire.test.ts

@@ -412,6 +412,47 @@ describe("operatorChoicesFromOptions / operatorResultFromSelection", () => {
 });
 
 describe("wireGates", () => {
+  test("notifies once when a permission gate reaches the screen", async () => {
+    const seen: string[] = [];
+    await withGates(
+      async ({ emitter }) => {
+        emitPermission(emitter, { id: "req-9" });
+        emitPermission(emitter, { id: "req-9" });
+      },
+      {
+        hooks: {
+          notify: {
+            notify: (message) => {
+              seen.push(message);
+              return true;
+            },
+          },
+        },
+      },
+    );
+    expect(seen).toEqual(["Approval needed"]);
+  });
+
+  test("notifies when an operator gate reaches the screen", async () => {
+    const seen: string[] = [];
+    await withGates(
+      async ({ emitter }) => {
+        emitOperator(emitter);
+      },
+      {
+        hooks: {
+          notify: {
+            notify: (message) => {
+              seen.push(message);
+              return true;
+            },
+          },
+        },
+      },
+    );
+    expect(seen).toEqual(["Input needed"]);
+  });
+
   test("subscribes exactly permission.gate and operator.gate; dispose removes both", async () => {
     await withGates(async ({ emitter, disposeGates }) => {
       expect(emitter.listenerCount("permission.gate")).toBe(1);

src/tui/gate-wire.ts

@@ -222,6 +222,13 @@ export interface GateLifecycleHooks {
   readonly onPrimaryOperatorAdmitted?: (event: OperatorGateEvent) => void;
   /** A marked primary ask_operator gate settled. */
   readonly onPrimaryOperatorSettled?: (event: OperatorGateEvent) => void;
+  /** Desktop/terminal notification. Fired once per gate id when that gate
+   * reaches the screen. Absent means no notification. */
+  readonly notify?: NotifierPort;
+}
+
+export interface NotifierPort {
+  notify(message: string, title?: string): boolean;
 }
 
 const NOOP_GATE_HOOKS: GateLifecycleHooks = {
@@ -275,6 +282,17 @@ export function wireGates(
   // tell whether the host has since opened a newer gate; comparing the
   // open-time capture against the current value closes only its own overlay.
   let overlayGeneration = 0;
+  const notifiedGateIds = new Set<string>();
+
+  function notifyOnce(id: string, message: string, title: string): void {
+    if (notifiedGateIds.has(id)) return;
+    notifiedGateIds.add(id);
+    try {
+      hooks.notify?.notify(message, title);
+    } catch {
+      // A notifier that throws must not block the gate.
+    }
+  }
 
   function openHost(open: () => void): void {
     overlayGeneration++;
@@ -388,6 +406,7 @@ export function wireGates(
       // screen, distinct from when it was raised (see
       // PermissionRequest.markDisplayed).
       ev.request.markDisplayed?.();
+      notifyOnce(ev.id, "Approval needed", "corbits");
       if (ev.timeoutMs !== undefined) {
         timer = setTimeout(() => {
           autoDeny(ev.timeoutMessage ?? "approval timed out; request denied");
@@ -489,6 +508,7 @@ export function wireGates(
 
     const open = (): void => {
       openedGeneration = overlayGeneration;
+      notifyOnce(ev.id, "Input needed", "corbits");
       if (ev.timeoutMs !== undefined) {
         timer = setTimeout(() => {
           autoCancel();

src/tui/product-host.ts

@@ -20,7 +20,7 @@ import {
 } from "./runtime-bridge.js";
 import type { ShellOutputFeed } from "../session/shell-output-feed.js";
 import { openAddProviderOverlay, openModelPickerOverlay } from "./overlays.js";
-import { wireGates } from "./gate-wire.js";
+import { wireGates, type NotifierPort } from "./gate-wire.js";
 import { createSystemClipboard } from "./system-clipboard.js";
 import { programStatusForChrome } from "./program-status.js";
 import {
@@ -268,6 +268,8 @@ export interface ProductHostConfig {
   /** OSC 7501 sink. Default calls `renderer.setProgramStatus` and ignores a
    * false return (terminal inactive, output full, or destroyed). */
   readonly programStatus?: ProgramStatusPort;
+  /** Gate attention ping. Default calls `renderer.triggerNotification`. */
+  readonly notifier?: NotifierPort;
 }
 
 export interface ProgramStatusPort {
@@ -616,6 +618,15 @@ export async function mountProductHost(
         setOperatorInputRequiredGate(shell, event),
       onPrimaryOperatorSettled: (event) =>
         clearOperatorInputRequired(shell, event.id),
+      notify: config.notifier ?? {
+        notify: (message, title) => {
+          try {
+            return renderer.triggerNotification(message, title);
+          } catch {
+            return false;
+          }
+        },
+      },
     });
   } catch (err: unknown) {
     try {