feat(tui): surface run and gate state as terminal program status

Author: TheGreatAxios

src/tui/chrome-state.test.ts

@@ -651,6 +651,11 @@ describe("chromeFromSession", () => {
     expect(zones.agents?.[0]?.label).toContain("explorer");
   });
 
+  test("copies a turn-level stall flag onto the live snapshot", () => {
+    expect(chromeFromSession({ stalled: true }).stalled).toBe(true);
+    expect(chromeFromSession({}).stalled).toBeUndefined();
+  });
+
   test("falls back agent id; empty bags hide", () => {
     const state = chromeFromSession({
       tasks: [],

src/tui/chrome-state.ts

@@ -82,6 +82,9 @@ export interface ChromeLiveState {
     readonly agentId: string;
     readonly description: string;
   } | null;
+  /** Turn-level stall (`isStalledForDisplay`). Absent means the host reads
+   * the live watchdog instead of this snapshot. */
+  readonly stalled?: boolean;
 }
 
 /** One rendered agents-panel row. `stalled` comes precomputed so the
@@ -513,6 +516,7 @@ export interface ChromeSessionInput {
   readonly tasks?: readonly ChromeSessionTask[] | null;
   readonly agents?: readonly ChromeSessionAgent[] | null;
   readonly observe?: ChromeLiveState["observe"];
+  readonly stalled?: boolean;
 }
 
 /** Map real session shapes (tasks / subagent store) into ChromeLiveState.
@@ -521,11 +525,13 @@ export function chromeFromSession(input: ChromeSessionInput): ChromeLiveState {
   const task = mapSessionTasks(input.tasks);
   const agents = mapSessionAgents(input.agents);
   const observe = input.observe ?? null;
+  const stalled = input.stalled;
 
   return {
     ...(task !== undefined ? { task } : {}),
     ...(agents !== undefined ? { agents } : {}),
     ...(observe !== null && observe !== undefined ? { observe } : {}),
+    ...(stalled !== undefined ? { stalled } : {}),
   };
 }
 

src/tui/product-host.ts

@@ -4,7 +4,11 @@
  */
 
 import { EventEmitter } from "node:events";
-import { createCliRenderer, type CliRenderer } from "@opentui/core";
+import {
+  createCliRenderer,
+  type CliRenderer,
+  type ProgramStatus,
+} from "@opentui/core";
 
 import { createLiveSessionPort } from "./live-session-port.js";
 import { checkWidthContract, widthContractNotice } from "./width-contract.js";
@@ -18,6 +22,7 @@ import type { ShellOutputFeed } from "../session/shell-output-feed.js";
 import { openAddProviderOverlay, openModelPickerOverlay } from "./overlays.js";
 import { wireGates } from "./gate-wire.js";
 import { createSystemClipboard } from "./system-clipboard.js";
+import { programStatusForChrome } from "./program-status.js";
 import {
   AGENTS_PANEL_LINGER_MS,
   agentsChromeNeedsSticky,
@@ -260,6 +265,13 @@ export interface ProductHostConfig {
    * resends wheel input as arrow keys; with it, drag-select is OpenTUI-owned
    * and auto-copies on mouse-up (Alt+M returns to native selection). */
   readonly useMouse?: boolean;
+  /** OSC 7501 sink. Default calls `renderer.setProgramStatus` and ignores a
+   * false return (terminal inactive, output full, or destroyed). */
+  readonly programStatus?: ProgramStatusPort;
+}
+
+export interface ProgramStatusPort {
+  set(status: ProgramStatus): boolean;
 }
 
 export interface ProductHost {
@@ -384,17 +396,41 @@ export async function mountProductHost(
   const agentsPanelLingerMs =
     config.agentsPanelLingerMs ?? AGENTS_PANEL_LINGER_MS;
   let chromeState: ChromeLiveState | null = config.chrome ?? null;
+  const programStatus: ProgramStatusPort = config.programStatus ?? {
+    set: (status) => {
+      try {
+        return renderer.setProgramStatus(status);
+      } catch {
+        return false;
+      }
+    },
+  };
+  let openGates = 0;
+  let lastProgramStatus = "";
+  const publishProgramStatus = (): void => {
+    const status = programStatusForChrome({
+      tasks: chromeState?.task,
+      agents: chromeState?.agents,
+      stalled: chromeState?.stalled ?? bridge.isTurnStalled(),
+      gateOpen: openGates > 0,
+    });
+    const key = JSON.stringify(status);
+    if (key === lastProgramStatus) return;
+    if (programStatus.set(status)) lastProgramStatus = key;
+  };
   const paintChromeZones = (): void => {
     if (chromeState === null) {
       setChromeZones(shell, { task: null, agents: null });
-      return;
+    } else {
+      setChromeZones(
+        shell,
+        formatChromeZones(chromeState, Date.now(), agentsPanelLingerMs),
+      );
     }
-    setChromeZones(
-      shell,
-      formatChromeZones(chromeState, Date.now(), agentsPanelLingerMs),
-    );
+    publishProgramStatus();
   };
   if (chromeState !== null) paintChromeZones();
+  else publishProgramStatus();
 
   let disposed = false;
   let resolveExit: (() => void) | undefined;
@@ -443,6 +479,8 @@ export async function mountProductHost(
       // formatAgentsPanel returns null after linger.
       if (stickyNeeded || stickyWasNeeded) {
         paintChromeZones();
+      } else {
+        publishProgramStatus();
       }
       stickyWasNeeded = stickyNeeded;
     } catch {
@@ -467,6 +505,11 @@ export async function mountProductHost(
     config.eventEmitter.off("compaction", onCompaction);
     config.eventEmitter.off("workflow", onWorkflow);
     bridge.dispose();
+    try {
+      programStatus.set({ state: "clear" });
+    } catch {
+      // renderer already gone
+    }
     // Cancels any flash still counting down: its expiry repaints into a
     // destroyed text buffer after teardown.
     setStatusFlash(shell, null);
@@ -559,8 +602,16 @@ export async function mountProductHost(
   let disposeGates: () => void;
   try {
     disposeGates = wireGates(config.eventEmitter, shell, {
-      onGateOpened: () => bridge.gateOpened(),
-      onGateClosed: () => bridge.gateClosed(),
+      onGateOpened: () => {
+        openGates += 1;
+        bridge.gateOpened();
+        publishProgramStatus();
+      },
+      onGateClosed: () => {
+        openGates = Math.max(0, openGates - 1);
+        bridge.gateClosed();
+        publishProgramStatus();
+      },
       onPrimaryOperatorAdmitted: (event) =>
         setOperatorInputRequiredGate(shell, event),
       onPrimaryOperatorSettled: (event) =>

src/tui/program-status.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+
+import { programStatusForChrome } from "./program-status.js";
+
+const doing = { title: "ship the mapper", status: "doing" as const };
+const todo = { title: "later", status: "todo" as const };
+const liveAgent = {
+  agentId: "a",
+  description: "read the tree",
+  status: "running" as const,
+  currentToolStartedAt: null,
+};
+
+describe("programStatusForChrome", () => {
+  test("an open gate blocks even while work is in flight", () => {
+    expect(
+      programStatusForChrome({
+        tasks: [doing],
+        agents: [liveAgent],
+        stalled: true,
+        gateOpen: true,
+      }),
+    ).toEqual({
+      state: "blocked",
+      app: "corbits",
+      title: "corbits",
+      message: "waiting on the operator",
+    });
+  });
+
+  test("a stalled turn is an error when no gate is open", () => {
+    expect(
+      programStatusForChrome({
+        tasks: [doing],
+        stalled: true,
+        gateOpen: false,
+      }).state,
+    ).toBe("error");
+  });
+
+  test("a doing task names the working record", () => {
+    expect(
+      programStatusForChrome({
+        tasks: [todo, doing],
+        stalled: false,
+        gateOpen: false,
+      }),
+    ).toMatchObject({ state: "working", message: "ship the mapper" });
+  });
+
+  test("a live agent is working when no task is doing", () => {
+    expect(
+      programStatusForChrome({
+        agents: [liveAgent],
+        stalled: false,
+        gateOpen: false,
+      }),
+    ).toMatchObject({ state: "working", message: "read the tree" });
+  });
+
+  test("an idle session reports idle, not clear", () => {
+    expect(
+      programStatusForChrome({ stalled: false, gateOpen: false }),
+    ).toMatchObject({ state: "idle", message: "idle" });
+  });
+
+  test("the report addresses the root record", () => {
+    const status = programStatusForChrome({
+      stalled: false,
+      gateOpen: false,
+    });
+    expect("id" in status).toBe(false);
+  });
+});

src/tui/program-status.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure OSC 7501 roll-up for one session. One root record (no lane id): a
+ * terminal that speaks the protocol replaces that record on every report.
+ * Lane-keyed records stay out until a real OSC 7511 terminal confirms them.
+ */
+
+import type { ProgramStatus } from "@opentui/core";
+
+import { agentLaneIsLive } from "../subagent/agent-progress.js";
+import type { ChromeAgentSession, ChromeTaskRow } from "./chrome-state.js";
+
+const MESSAGE_MAX = 80;
+
+export interface ProgramStatusInput {
+  readonly tasks?: readonly ChromeTaskRow[] | null | undefined;
+  readonly agents?: readonly ChromeAgentSession[] | null | undefined;
+  /** Turn-level stall from `isStalledForDisplay`, not a per-lane clock. */
+  readonly stalled: boolean;
+  /** A permission or operator gate is outstanding, queued or on screen. */
+  readonly gateOpen: boolean;
+}
+
+export function programStatusForChrome(
+  input: ProgramStatusInput,
+): ProgramStatus {
+  if (input.gateOpen) {
+    return {
+      state: "blocked",
+      app: "corbits",
+      title: "corbits",
+      message: "waiting on the operator",
+    };
+  }
+  if (input.stalled) {
+    return {
+      state: "error",
+      app: "corbits",
+      title: "corbits",
+      message: "stalled",
+    };
+  }
+  const doing = input.tasks?.find((task) => task.status === "doing");
+  const live = input.agents?.find((agent) => agentLaneIsLive(agent));
+  if (doing !== undefined || live !== undefined) {
+    const raw = doing?.title ?? live?.description ?? "working";
+    return {
+      state: "working",
+      app: "corbits",
+      title: "corbits",
+      message: clip(raw.length > 0 ? raw : "working"),
+    };
+  }
+  return {
+    state: "idle",
+    app: "corbits",
+    title: "corbits",
+    message: "idle",
+  };
+}
+
+function clip(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= MESSAGE_MAX) return flat;
+  return `${flat.slice(0, MESSAGE_MAX - 3)}...`;
+}

src/tui/runtime-bridge.ts

@@ -237,6 +237,9 @@ export interface SessionBridge {
   dispose: () => void;
   /** Current derived turn phase (progress label, stall clock, quota window). */
   readonly turn: TurnState;
+  /** Turn-level stall the program-status roll-up paints. Same predicate as
+   * the lockup (`isStalledForDisplay`). */
+  readonly isTurnStalled: () => boolean;
   readonly shell: AppShell;
   /** Refresh `spawn_agent` rows with live progress for the worker lifetime. */
   syncAgentProgress: (sessions: readonly TaskProgressSession[]) => void;
@@ -2250,6 +2253,7 @@ export function attachSessionBridge(
     get turn() {
       return bag.turn;
     },
+    isTurnStalled: () => isStalledForDisplay(stallArgsFor(now())),
     syncAgentProgress: (sessions) => {
       if (bag.disposed) return;
       bag.agentSessions = sessions;