TUI: guide pairing-required recovery in disconnect state

src/tui/tui.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 import { getSlashCommands, parseCommand } from "./commands.js";
-import { resolveFinalAssistantText, resolveTuiSessionKey } from "./tui.js";
+import {
+  resolveFinalAssistantText,
+  resolveGatewayDisconnectState,
+  resolveTuiSessionKey,
+} from "./tui.js";
 
 describe("resolveFinalAssistantText", () => {
   it("falls back to streamed text when final text is empty", () => {
@@ -67,3 +71,19 @@ describe("resolveTuiSessionKey", () => {
     ).toBe("agent:ops:incident");
   });
 });
+
+describe("resolveGatewayDisconnectState", () => {
+  it("returns pairing recovery guidance when disconnect reason requires pairing", () => {
+    const state = resolveGatewayDisconnectState("gateway closed (1008): pairing required");
+    expect(state.connectionStatus).toContain("pairing required");
+    expect(state.activityStatus).toBe("pairing required: run openclaw devices list");
+    expect(state.pairingHint).toContain("openclaw devices list");
+  });
+
+  it("falls back to idle for generic disconnect reasons", () => {
+    const state = resolveGatewayDisconnectState("network timeout");
+    expect(state.connectionStatus).toBe("gateway disconnected: network timeout");
+    expect(state.activityStatus).toBe("idle");
+    expect(state.pairingHint).toBeUndefined();
+  });
+});

src/tui/tui.ts

@@ -195,6 +195,26 @@ export function resolveTuiSessionKey(params: {
   return `agent:${params.currentAgentId}:${trimmed}`;
 }
 
+export function resolveGatewayDisconnectState(reason?: string): {
+  connectionStatus: string;
+  activityStatus: string;
+  pairingHint?: string;
+} {
+  const reasonLabel = reason?.trim() ? reason.trim() : "closed";
+  if (/pairing required/i.test(reasonLabel)) {
+    return {
+      connectionStatus: `gateway disconnected: ${reasonLabel}`,
+      activityStatus: "pairing required: run openclaw devices list",
+      pairingHint:
+        "Pairing required. Run `openclaw devices list`, approve your request ID, then reconnect.",
+    };
+  }
+  return {
+    connectionStatus: `gateway disconnected: ${reasonLabel}`,
+    activityStatus: "idle",
+  };
+}
+
 export async function runTui(opts: TuiOptions) {
   const config = loadConfig();
   const initialSessionInput = (opts.session ?? "").trim();
@@ -213,6 +233,7 @@ export async function runTui(opts: TuiOptions) {
   let wasDisconnected = false;
   let toolsExpanded = false;
   let showThinking = false;
+  let pairingHintShown = false;
   const localRunIds = new Set<string>();
 
   const deliverDefault = opts.deliver ?? false;
@@ -772,6 +793,7 @@ export async function runTui(opts: TuiOptions) {
 
   client.onConnected = () => {
     isConnected = true;
+    pairingHintShown = false;
     const reconnected = wasDisconnected;
     wasDisconnected = false;
     setConnectionStatus("connected");
@@ -794,9 +816,13 @@ export async function runTui(opts: TuiOptions) {
     isConnected = false;
     wasDisconnected = true;
     historyLoaded = false;
-    const reasonLabel = reason?.trim() ? reason.trim() : "closed";
-    setConnectionStatus(`gateway disconnected: ${reasonLabel}`, 5000);
-    setActivityStatus("idle");
+    const disconnectState = resolveGatewayDisconnectState(reason);
+    setConnectionStatus(disconnectState.connectionStatus, 5000);
+    setActivityStatus(disconnectState.activityStatus);
+    if (disconnectState.pairingHint && !pairingHintShown) {
+      pairingHintShown = true;
+      chatLog.addSystem(disconnectState.pairingHint);
+    }
     updateFooter();
     tui.requestRender();
   };