fix(gateway): stop terminal WhatsApp restart loops (#78511)

openperf · steipete · web-flow · commit e29448df08e2 · 2026-07-05T05:49:33.000-07:00
* fix(gateway): prevent restart loops after terminal WhatsApp disconnects Track `terminalDisconnect` through the WhatsApp status controller, channel runtime snapshot, and `ChannelAccountSnapshot` so the health-monitor and the `ChannelManager` task-exit handler both skip auto-restart when Baileys signals a terminal session end (loggedOut / connectionReplaced). Adds a `terminal-disconnect` `ChannelHealthEvaluationReason` so the policy layer returns a stable, named reason rather than falling through to `not-running`, preventing unbounded WebSocket/heap growth on multi-tenant gateways. Fixes #78419. * fix(gateway): prioritize terminal disconnect recovery Co-authored-by: openperf <16864032@qq.com> * docs(changelog): move WhatsApp restart fix to unreleased --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- **WhatsApp restart recovery:** stop automatic restart loops after logged-out or connection-replaced disconnects until the account reconnects. (#78511) Thanks @openperf.
 - **iMessage group warnings:** suppress the false drop-all startup warning when an effective group sender allowlist can admit groups, and point true empty-allowlist configurations at the correct remedy. (#100046)
 
 ## 2026.7.1
diff --git a/extensions/whatsapp/src/auto-reply/monitor-state.test.ts b/extensions/whatsapp/src/auto-reply/monitor-state.test.ts
@@ -133,4 +133,47 @@ describe("createWebChannelStatusController", () => {
       loggedOut: false,
     });
   });
+
+  it.each([
+    { healthState: "logged-out", statusCode: 401, terminalDisconnect: true },
+    { healthState: "conflict", statusCode: 440, terminalDisconnect: true },
+    { healthState: "reconnecting", statusCode: 408, terminalDisconnect: false },
+  ] as const)(
+    "sets terminalDisconnect=$terminalDisconnect after a $healthState stop",
+    ({ healthState, statusCode, terminalDisconnect }) => {
+      const patches: Record<string, unknown>[] = [];
+      const controller = createWebChannelStatusController((s) => patches.push({ ...s }));
+
+      controller.noteConnected(1000);
+      controller.noteClose({
+        at: 2000,
+        statusCode,
+        error: healthState,
+        reconnectAttempts: healthState === "reconnecting" ? 1 : 0,
+        healthState,
+      });
+      controller.markStopped(2100);
+
+      expect(patches.at(-1)!.terminalDisconnect).toBe(terminalDisconnect);
+    },
+  );
+
+  it("clears terminalDisconnect on noteConnected after a terminal stop", () => {
+    const patches: Record<string, unknown>[] = [];
+    const controller = createWebChannelStatusController((s) => patches.push({ ...s }));
+
+    controller.noteConnected(1000);
+    controller.noteClose({
+      at: 2000,
+      statusCode: 401,
+      error: "logged out",
+      reconnectAttempts: 0,
+      healthState: "logged-out",
+    });
+    controller.markStopped(2100);
+    expect(patches.at(-1)!.terminalDisconnect).toBe(true);
+
+    controller.noteConnected(3000);
+    expect(patches.at(-1)!.terminalDisconnect).toBeUndefined();
+  });
 });
diff --git a/extensions/whatsapp/src/auto-reply/monitor-state.ts b/extensions/whatsapp/src/auto-reply/monitor-state.ts
@@ -50,6 +50,7 @@ export function createWebChannelStatusController(statusSink?: (status: WebChanne
       }
       status.lastError = null;
       status.healthState = "healthy";
+      status.terminalDisconnect = undefined;
       emit();
     },
     noteInbound(at = Date.now()) {
@@ -119,6 +120,8 @@ export function createWebChannelStatusController(statusSink?: (status: WebChanne
       status.running = false;
       status.connected = false;
       status.lastEventAt = at;
+      status.terminalDisconnect =
+        status.healthState === "logged-out" || status.healthState === "conflict";
       if (!isTerminalHealthState(status.healthState)) {
         status.healthState = "stopped";
       }
diff --git a/extensions/whatsapp/src/auto-reply/types.ts b/extensions/whatsapp/src/auto-reply/types.ts
@@ -35,6 +35,7 @@ export type WebChannelStatus = {
   lastRunActivityAt?: number | null;
   lastError?: string | null;
   healthState?: WebChannelHealthState;
+  terminalDisconnect?: boolean;
 };
 
 export type WebMonitorTuning = {
diff --git a/extensions/whatsapp/src/channel.ts b/extensions/whatsapp/src/channel.ts
@@ -288,6 +288,9 @@ export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
             lastRunActivityAt: snapshot.lastRunActivityAt ?? null,
             lastError: snapshot.lastError ?? null,
             healthState: snapshot.healthState ?? undefined,
+            ...(snapshot.terminalDisconnect
+              ? { terminalDisconnect: snapshot.terminalDisconnect }
+              : {}),
           };
         },
         resolveAccountSnapshot: async ({ account, runtime }) => {
@@ -315,6 +318,9 @@ export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
               busy: runtime?.busy ?? false,
               lastRunActivityAt: runtime?.lastRunActivityAt ?? null,
               healthState: runtime?.healthState ?? undefined,
+              ...(runtime?.terminalDisconnect
+                ? { terminalDisconnect: runtime.terminalDisconnect }
+                : {}),
               dmPolicy: account.dmPolicy,
               allowFrom: account.allowFrom,
             },
diff --git a/src/channels/account-snapshot-fields.test.ts b/src/channels/account-snapshot-fields.test.ts
@@ -60,4 +60,15 @@ describe("projectSafeChannelAccountSnapshotFields", () => {
       lastTransportActivityAt: 456,
     });
   });
+
+  it("projects terminalDisconnect when present and omits it when absent", () => {
+    const withFlag = projectSafeChannelAccountSnapshotFields({
+      connected: false,
+      terminalDisconnect: true,
+    });
+    expect(withFlag.terminalDisconnect).toBe(true);
+
+    const withoutFlag = projectSafeChannelAccountSnapshotFields({ connected: false });
+    expect(withoutFlag).not.toHaveProperty("terminalDisconnect");
+  });
 });
diff --git a/src/channels/account-snapshot-fields.ts b/src/channels/account-snapshot-fields.ts
@@ -237,6 +237,9 @@ export function projectSafeChannelAccountSnapshotFields(
       : {}),
     ...(statusState ? { statusState } : {}),
     ...(healthState ? { healthState } : {}),
+    ...(readBoolean(record, "terminalDisconnect") !== undefined
+      ? { terminalDisconnect: readBoolean(record, "terminalDisconnect") }
+      : {}),
     ...(readBoolean(record, "busy") !== undefined ? { busy: readBoolean(record, "busy") } : {}),
     ...(readNumber(record, "activeRuns") !== undefined
       ? { activeRuns: readNumber(record, "activeRuns") }
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
@@ -213,6 +213,7 @@ export type ChannelAccountSnapshot = {
   lastTransportActivityAt?: number | null;
   lastError?: string | null;
   healthState?: string;
+  terminalDisconnect?: boolean;
   lastStartAt?: number | null;
   lastStopAt?: number | null;
   lastInboundAt?: number | null;
diff --git a/src/gateway/channel-health-monitor.test.ts b/src/gateway/channel-health-monitor.test.ts
@@ -274,6 +274,36 @@ describe("channel-health-monitor", () => {
     await expectNoStart(manager);
   });
 
+  it("does not restart a channel with terminalDisconnect set", async () => {
+    const manager = createSnapshotManager({
+      whatsapp: {
+        default: {
+          running: false,
+          enabled: true,
+          configured: true,
+          terminalDisconnect: true,
+        },
+      },
+    });
+    await expectNoRestart(manager);
+  });
+
+  it("restarts a stopped channel without terminalDisconnect", async () => {
+    const manager = createSnapshotManager({
+      whatsapp: {
+        default: {
+          running: false,
+          enabled: true,
+          configured: true,
+          terminalDisconnect: false,
+        },
+      },
+    });
+    const monitor = await startAndRunCheck(manager);
+    expect(manager.startChannel).toHaveBeenCalledWith("whatsapp", "default");
+    monitor.stop();
+  });
+
   it("skips manually stopped channels", async () => {
     const manager = createSnapshotManager(
       {
diff --git a/src/gateway/channel-health-monitor.ts b/src/gateway/channel-health-monitor.ts
@@ -138,6 +138,12 @@ export function startChannelHealthMonitor(deps: ChannelHealthMonitorDeps): Chann
           if (health.healthy) {
             continue;
           }
+          if (health.reason === "terminal-disconnect") {
+            log.info?.(
+              `[${channelId}:${accountId}] health-monitor: skipping restart, terminal disconnect`,
+            );
+            continue;
+          }
 
           const key = rKey(channelId, accountId);
           const record = restartRecords.get(key) ?? {
diff --git a/src/gateway/channel-health-policy.test.ts b/src/gateway/channel-health-policy.test.ts
@@ -184,6 +184,28 @@ describe("evaluateChannelHealth", () => {
     });
     expect(evaluation).toEqual({ healthy: false, reason: "stale-socket" });
   });
+
+  it.each([
+    {
+      name: "distinguishes a stopped terminal channel",
+      snapshot: { running: false, terminalDisconnect: true },
+      expected: { healthy: false, reason: "terminal-disconnect" },
+    },
+    {
+      name: "keeps ordinary stopped channels restartable",
+      snapshot: { running: false, terminalDisconnect: false },
+      expected: { healthy: false, reason: "not-running" },
+    },
+    {
+      name: "ignores stale terminal state while running",
+      snapshot: { running: true, connected: true, terminalDisconnect: true },
+      expected: { healthy: true, reason: "healthy" },
+    },
+  ] as const)("$name", ({ snapshot, expected }) => {
+    expect(
+      evaluateHealth({ enabled: true, configured: true, ...snapshot }, { channelId: "whatsapp" }),
+    ).toEqual(expected);
+  });
 });
 
 describe("resolveChannelRestartReason", () => {
diff --git a/src/gateway/channel-health-policy.ts b/src/gateway/channel-health-policy.ts
@@ -17,12 +17,14 @@ type ChannelHealthSnapshot = {
   lastStartAt?: number | null;
   reconnectAttempts?: number;
   mode?: string;
+  terminalDisconnect?: boolean;
 };
 
 type ChannelHealthEvaluationReason =
   | "healthy"
   | "unmanaged"
   | "not-running"
+  | "terminal-disconnect"
   | "busy"
   | "stuck"
   | "startup-connect-grace"
@@ -60,6 +62,9 @@ export function evaluateChannelHealth(
   if (!isManagedAccount(snapshot)) {
     return { healthy: true, reason: "unmanaged" };
   }
+  if (!snapshot.running && snapshot.terminalDisconnect) {
+    return { healthy: false, reason: "terminal-disconnect" };
+  }
   if (!snapshot.running) {
     return { healthy: false, reason: "not-running" };
   }
diff --git a/src/gateway/server-channels.test.ts b/src/gateway/server-channels.test.ts
@@ -365,6 +365,29 @@ describe("server-channels auto restart", () => {
     expect(startAccount).toHaveBeenCalledTimes(1);
   });
 
+  it("does not auto-restart a channel task exit marked as terminal disconnect", async () => {
+    const startAccount = vi.fn(
+      async ({
+        setStatus,
+        accountId,
+      }: {
+        setStatus: ChannelGatewayContext["setStatus"];
+        accountId: string;
+      }) => {
+        setStatus({ accountId, terminalDisconnect: true });
+      },
+    );
+    installTestRegistry(createTestPlugin({ startAccount }));
+    const manager = createManager();
+
+    await manager.startChannels();
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(startAccount).toHaveBeenCalledTimes(1);
+    const snapshot = manager.getRuntimeSnapshot();
+    expect(snapshot.channelAccounts.discord?.[DEFAULT_ACCOUNT_ID]?.terminalDisconnect).toBe(true);
+  });
+
   it("consumes rejected stop tasks during manual abort", async () => {
     const unhandledRejection = vi.fn();
     process.on("unhandledRejection", unhandledRejection);
@@ -467,6 +490,38 @@ describe("server-channels auto restart", () => {
     expect(hoisted.sleepWithAbort).not.toHaveBeenCalled();
   });
 
+  it("does not restart when a timed-out recovery stop settles as terminal", async () => {
+    const releaseFirstTask = createDeferred();
+    const startAccount = vi.fn(async (ctx: ChannelGatewayContext<TestAccount>) => {
+      ctx.abortSignal.addEventListener("abort", () => {}, { once: true });
+      await releaseFirstTask.promise;
+      ctx.setStatus({ accountId: DEFAULT_ACCOUNT_ID, terminalDisconnect: true });
+    });
+    installTestRegistry(createTestPlugin({ startAccount }));
+    const manager = createManager();
+
+    await manager.startChannels();
+    const stopTask = manager.stopChannel("discord", DEFAULT_ACCOUNT_ID, { manual: false });
+    await vi.advanceTimersByTimeAsync(5_000);
+    await stopTask;
+    await manager.startChannel("discord", DEFAULT_ACCOUNT_ID);
+
+    releaseFirstTask.resolve();
+    await waitForMicrotaskCondition(
+      () =>
+        manager.getRuntimeSnapshot().channelAccounts.discord?.[DEFAULT_ACCOUNT_ID]
+          ?.restartPending === false,
+      "expected terminal recovery completion to clear restart state",
+    );
+
+    const account = manager.getRuntimeSnapshot().channelAccounts.discord?.[DEFAULT_ACCOUNT_ID];
+    expect(startAccount).toHaveBeenCalledTimes(1);
+    expect(account?.terminalDisconnect).toBe(true);
+    expect(account?.restartPending).toBe(false);
+    expect(account?.reconnectAttempts).toBe(0);
+    expect(hoisted.sleepWithAbort).not.toHaveBeenCalled();
+  });
+
   it("keeps recovery timeout diagnostics when a stale task reports connected after abort", async () => {
     let emitLateStatus: (() => void) | undefined;
     const startAccount = vi.fn(async (ctx: ChannelGatewayContext<TestAccount>) => {
diff --git a/src/gateway/server-channels.ts b/src/gateway/server-channels.ts
@@ -681,6 +681,20 @@ export function createChannelManager(opts: ChannelManagerOptions): ChannelManage
                 recoveryStartRequested.delete(rKey);
                 return;
               }
+              if (getRuntime(channelId, id).terminalDisconnect) {
+                // Authentication/session termination wins over pending recovery.
+                // Leaving recovery state behind would restart a channel that needs user action.
+                recoveryStopTimedOut.delete(rKey);
+                recoveryStartRequested.delete(rKey);
+                restartAttempts.delete(rKey);
+                setRuntime(channelId, id, {
+                  accountId: id,
+                  restartPending: false,
+                  reconnectAttempts: 0,
+                });
+                log.info?.(`[${id}] auto-restart skipped, terminal disconnect`);
+                return;
+              }
               if (recoveryStopTimedOut.has(rKey)) {
                 recoveryStopTimedOut.delete(rKey);
                 if (!recoveryStartRequested.delete(rKey)) {
diff --git a/src/gateway/server-methods/channels.status.test.ts b/src/gateway/server-methods/channels.status.test.ts
@@ -336,6 +336,36 @@ describe("channelsHandlers channels.status", () => {
     expect(account.configured).toBe(true);
   });
 
+  it("annotates terminal-disconnect accounts with terminal-disconnect health state", async () => {
+    mocks.applyPluginAutoEnable.mockReturnValue({ config: { autoEnabled: true }, changes: [] });
+    mocks.buildChannelAccountSnapshot.mockResolvedValue({
+      accountId: "default",
+      enabled: true,
+      configured: true,
+      running: false,
+      terminalDisconnect: true,
+    });
+    const respond = vi.fn();
+
+    await channelsHandlers["channels.status"](
+      createOptions({ probe: false, timeoutMs: 2000 }, { respond }),
+    );
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({
+        channelAccounts: {
+          whatsapp: [
+            expect.objectContaining({
+              healthState: "terminal-disconnect",
+            }),
+          ],
+        },
+      }),
+      undefined,
+    );
+  });
+
   it("annotates unhealthy channel snapshots and includes event-loop health", async () => {
     const now = Date.now();
     mocks.applyPluginAutoEnable.mockReturnValue({ config: { autoEnabled: true }, changes: [] });
diff --git a/src/plugin-sdk/status-helpers.test.ts b/src/plugin-sdk/status-helpers.test.ts
@@ -349,6 +349,24 @@ describe("buildRuntimeAccountStatusSnapshot", () => {
         probe: undefined,
       },
     },
+    {
+      name: "projects terminalDisconnect when set",
+      input: {
+        runtime: {
+          running: false,
+          healthState: "logged-out",
+          terminalDisconnect: true,
+        },
+      },
+      extra: undefined,
+      expected: {
+        ...defaultRuntimeState,
+        running: false,
+        healthState: "logged-out",
+        terminalDisconnect: true,
+        probe: undefined,
+      },
+    },
   ])("$name", ({ input, extra, expected }) => {
     expect(buildRuntimeAccountStatusSnapshot(input, extra)).toEqual(expected);
   });
diff --git a/src/plugin-sdk/status-helpers.ts b/src/plugin-sdk/status-helpers.ts
