Expose WhatsApp responsiveness doctor lint findings (#98406)

giodl73-repo · web-flow · commit 6011c9e16d21 · 2026-07-03T11:55:10.000-07:00
Adds a default-disabled Doctor lint check for WhatsApp responsiveness pressure while keeping real cleanup in the existing doctor --fix path. Verification: - Focused WhatsApp responsiveness/contribution Vitest passed (71 tests). - Changed-file oxfmt passed. - Changed-file oxlint with core tsconfig passed. - SDK surface report passed. - SDK export sync passed. - git diff --check passed. - Selected source CLI proof passed earlier on this head: doctor --lint --json --only core/doctor/whatsapp-responsiveness exited 0, ran 1 check, and did not create <state>/identity/device.json. - Exact-head hosted checks passed/skipped on 39f0039; older cancelled proof/auto-response runs were superseded by passing current runs. Maintainer notes: - ClawSweeper platinum hermit / ready for maintainer review. - Accepted the opt-in lint check id and warning copy on the PR. - No public config/plugin/SDK/persisted data contract change; default doctor --lint remains unchanged.
diff --git a/src/commands/doctor-whatsapp-responsiveness.test.ts b/src/commands/doctor-whatsapp-responsiveness.test.ts
@@ -16,8 +16,12 @@ vi.mock("../../packages/terminal-core/src/note.js", () => ({
   note: noteMock,
 }));
 
-const { listLocalTuiProcesses, noteWhatsappResponsivenessHealth, terminateLocalTuiProcesses } =
-  await import("./doctor-whatsapp-responsiveness.js");
+const {
+  collectWhatsappResponsivenessHealthFindings,
+  listLocalTuiProcesses,
+  noteWhatsappResponsivenessHealth,
+  terminateLocalTuiProcesses,
+} = await import("./doctor-whatsapp-responsiveness.js");
 
 describe("doctor WhatsApp responsiveness", () => {
   beforeEach(() => {
@@ -39,11 +43,16 @@ describe("doctor WhatsApp responsiveness", () => {
       ].join("\n"),
     });
 
-    expect(listLocalTuiProcesses()).toEqual([
-      { pid: 101, command: "openclaw-tui" },
-      { pid: 104, command: "openclaw tui --local" },
-      { pid: 105, command: "/usr/bin/openclaw chat" },
-    ]);
+    if (process.platform === "win32") {
+      expect(listLocalTuiProcesses()).toEqual([]);
+      expect(spawnSyncMock).not.toHaveBeenCalled();
+    } else {
+      expect(listLocalTuiProcesses()).toEqual([
+        { pid: 101, command: "openclaw-tui" },
+        { pid: 104, command: "openclaw tui --local" },
+        { pid: 105, command: "/usr/bin/openclaw chat" },
+      ]);
+    }
   });
 
   it("terminates stale local TUI processes with a kill fallback", async () => {
@@ -118,6 +127,93 @@ describe("doctor WhatsApp responsiveness", () => {
     );
   });
 
+  it("collects a warning finding for local TUI pressure when WhatsApp is enabled", () => {
+    const cfg = { channels: { whatsapp: { enabled: true } } } as OpenClawConfig;
+
+    const findings = collectWhatsappResponsivenessHealthFindings({
+      cfg,
+      status: {
+        eventLoop: {
+          degraded: true,
+          reasons: ["event_loop_delay"],
+          intervalMs: 30_000,
+          delayP99Ms: 42,
+          delayMaxMs: 12_000,
+          utilization: 0.3,
+          cpuCoreRatio: 0.4,
+        },
+      },
+      listLocalTuiProcesses: () => [{ pid: 101, command: "openclaw-tui" }],
+    });
+
+    expect(findings).toEqual([
+      expect.objectContaining({
+        checkId: "core/doctor/whatsapp-responsiveness",
+        severity: "warning",
+        path: "channels.whatsapp",
+        target: "101",
+        requirement: "local-tui-event-loop-pressure",
+        fixHint: expect.stringContaining("openclaw doctor --fix"),
+      }),
+    ]);
+  });
+
+  it("keeps WhatsApp responsiveness findings quiet without the exact pressure signal", () => {
+    const cfg = { channels: { whatsapp: { enabled: true } } } as OpenClawConfig;
+
+    expect(
+      collectWhatsappResponsivenessHealthFindings({
+        cfg,
+        status: {
+          eventLoop: {
+            degraded: false,
+            reasons: [],
+            intervalMs: 1,
+            delayP99Ms: 0,
+            delayMaxMs: 0,
+            utilization: 0,
+            cpuCoreRatio: 0,
+          },
+        },
+        listLocalTuiProcesses: () => [{ pid: 101, command: "openclaw-tui" }],
+      }),
+    ).toEqual([]);
+    expect(
+      collectWhatsappResponsivenessHealthFindings({
+        cfg,
+        status: {
+          eventLoop: {
+            degraded: true,
+            reasons: ["event_loop_delay"],
+            intervalMs: 30_000,
+            delayP99Ms: 42,
+            delayMaxMs: 12_000,
+            utilization: 0.3,
+            cpuCoreRatio: 0.4,
+          },
+        },
+        listLocalTuiProcesses: () => [],
+      }),
+    ).toEqual([]);
+    expect(
+      collectWhatsappResponsivenessHealthFindings({
+        cfg: { channels: { whatsapp: { enabled: false } } } as OpenClawConfig,
+        status: {
+          eventLoop: {
+            degraded: true,
+            reasons: ["event_loop_delay"],
+            intervalMs: 30_000,
+            delayP99Ms: 42,
+            delayMaxMs: 12_000,
+            utilization: 0.3,
+            cpuCoreRatio: 0.4,
+          },
+        },
+        listLocalTuiProcesses: () => [{ pid: 101, command: "openclaw-tui" }],
+      }),
+    ).toEqual([]);
+  });
+
   it("does not treat generic model routing as a WhatsApp-only issue", async () => {
     const cfg = {
       channels: { whatsapp: { enabled: true } },
diff --git a/src/commands/doctor-whatsapp-responsiveness.ts b/src/commands/doctor-whatsapp-responsiveness.ts
@@ -4,6 +4,7 @@ import path from "node:path";
 import { note } from "../../packages/terminal-core/src/note.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import type { HealthFinding } from "../flows/health-checks.js";
 import type { StatusSummary } from "./status.types.js";
 
 type LocalTuiProcess = {
@@ -18,6 +19,7 @@ type ProcessController = {
 };
 
 const LOCAL_TUI_SUBCOMMANDS = new Set(["chat", "terminal", "tui"]);
+const WHATSAPP_RESPONSIVENESS_CHECK_ID = "core/doctor/whatsapp-responsiveness";
 
 function tokenizeCommandLine(command: string): string[] {
   return command.trim().split(/\s+/u).filter(Boolean);
@@ -93,6 +95,43 @@ function formatPidList(processes: LocalTuiProcess[]): string {
   return processes.map((proc) => String(proc.pid)).join(", ");
 }
 
+/** Collects read-only structured findings for WhatsApp responsiveness pressure. */
+export function collectWhatsappResponsivenessHealthFindings(params: {
+  cfg: OpenClawConfig;
+  status?: Pick<StatusSummary, "eventLoop"> | null;
+  listLocalTuiProcesses?: () => LocalTuiProcess[];
+}): readonly HealthFinding[] {
+  if (!hasWhatsappEnabled(params.cfg)) {
+    return [];
+  }
+
+  const eventLoop = params.status?.eventLoop;
+  if (eventLoop?.degraded !== true) {
+    return [];
+  }
+
+  const tuiProcesses = (params.listLocalTuiProcesses ?? listLocalTuiProcesses)();
+  if (tuiProcesses.length === 0) {
+    return [];
+  }
+
+  const pids = formatPidList(tuiProcesses);
+  return [
+    {
+      checkId: WHATSAPP_RESPONSIVENESS_CHECK_ID,
+      severity: "warning",
+      message:
+        "Gateway event loop is degraded while local TUI clients are running; WhatsApp replies can queue behind TUI startup/session refresh work.",
+      path: "channels.whatsapp",
+      target: pids,
+      requirement: "local-tui-event-loop-pressure",
+      fixHint: `Close local TUI sessions (${pids}), or run ${formatCliCommand(
+        "openclaw doctor --fix",
+      )}.`,
+    },
+  ];
+}
+
 function isProcessAlive(controller: ProcessController, pid: number): boolean {
   try {
     controller.kill(pid, 0);
diff --git a/src/flows/doctor-health-contributions.test.ts b/src/flows/doctor-health-contributions.test.ts
@@ -28,6 +28,7 @@ const mocks = vi.hoisted(() => ({
   noteLegacyCodexProviderOverride: vi.fn(),
   noteMemorySearchHealth: vi.fn().mockResolvedValue(undefined),
   buildGatewayConnectionDetails: vi.fn(() => ({ message: "gateway details" })),
+  callGateway: vi.fn(),
   resolveSecretInputRef: vi.fn((params: { value?: unknown }) => ({
     ref:
       params.value === "exec-token"
@@ -100,6 +101,8 @@ const mocks = vi.hoisted(() => ({
   collectDiskSpaceHealthFindings: vi.fn((): readonly HealthFinding[] => []),
   collectHeartbeatTemplateHealthFindings: vi.fn(async () => [] as unknown[]),
   maybeRepairHeartbeatTemplate: vi.fn().mockResolvedValue(undefined),
+  collectWhatsappResponsivenessHealthFindings: vi.fn((): readonly HealthFinding[] => []),
+  noteWhatsappResponsivenessHealth: vi.fn().mockResolvedValue(undefined),
   collectDevicePairingHealthFindings: vi.fn(async () => []),
   scanConfiguredChannelPluginBlockers: vi.fn(
     (): Array<{ channelId: string; pluginId: string; reason: string }> => [],
@@ -213,6 +216,7 @@ vi.mock("../commands/doctor-memory-search.js", () => ({
 
 vi.mock("../gateway/call.js", () => ({
   buildGatewayConnectionDetails: mocks.buildGatewayConnectionDetails,
+  callGateway: mocks.callGateway,
 }));
 
 vi.mock("../commands/doctor-platform-notes.js", () => ({
@@ -338,6 +342,11 @@ vi.mock("../commands/doctor-heartbeat-template-repair.js", () => ({
   maybeRepairHeartbeatTemplate: mocks.maybeRepairHeartbeatTemplate,
 }));
 
+vi.mock("../commands/doctor-whatsapp-responsiveness.js", () => ({
+  collectWhatsappResponsivenessHealthFindings: mocks.collectWhatsappResponsivenessHealthFindings,
+  noteWhatsappResponsivenessHealth: mocks.noteWhatsappResponsivenessHealth,
+}));
+
 vi.mock("../commands/doctor-device-pairing.js", () => ({
   collectDevicePairingHealthFindings: mocks.collectDevicePairingHealthFindings,
   noteDevicePairingHealth: vi.fn().mockResolvedValue(undefined),
@@ -428,6 +437,8 @@ describe("doctor health contributions", () => {
     mocks.noteMemorySearchHealth.mockResolvedValue(undefined);
     mocks.buildGatewayConnectionDetails.mockClear();
     mocks.buildGatewayConnectionDetails.mockReturnValue({ message: "gateway details" });
+    mocks.callGateway.mockReset();
+    mocks.callGateway.mockResolvedValue({});
     mocks.resolveSecretInputRef.mockClear();
     mocks.resolveGatewayAuth.mockClear();
     mocks.resolveGatewayAuth.mockReturnValue({ mode: "token", token: undefined });
@@ -542,6 +553,10 @@ describe("doctor health contributions", () => {
     mocks.collectHeartbeatTemplateHealthFindings.mockResolvedValue([]);
     mocks.maybeRepairHeartbeatTemplate.mockReset();
     mocks.maybeRepairHeartbeatTemplate.mockResolvedValue(undefined);
+    mocks.collectWhatsappResponsivenessHealthFindings.mockReset();
+    mocks.collectWhatsappResponsivenessHealthFindings.mockReturnValue([]);
+    mocks.noteWhatsappResponsivenessHealth.mockReset();
+    mocks.noteWhatsappResponsivenessHealth.mockResolvedValue(undefined);
     mocks.collectDevicePairingHealthFindings.mockReset();
     mocks.collectDevicePairingHealthFindings.mockResolvedValue([]);
     mocks.scanConfiguredChannelPluginBlockers.mockReset();
@@ -1362,6 +1377,7 @@ describe("doctor health contributions", () => {
     expect(contributionIds).toContain("core/doctor/stale-plugin-runtime-symlinks");
     expect(contributionIds).toContain("core/doctor/disk-space");
     expect(contributionIds).toContain("core/doctor/heartbeat-template");
+    expect(contributionIds).toContain("core/doctor/whatsapp-responsiveness");
     expect(contributionIds).toContain("core/doctor/device-pairing");
     expect(contributionIds).toContain("core/doctor/channel-plugin-blockers");
     expect(contributionIds).toContain("core/doctor/tool-result-cap");
@@ -1694,6 +1710,125 @@ describe("doctor health contributions", () => {
     expect(mocks.collectDiskSpaceHealthFindings).toHaveBeenCalledWith(ctx.cfg);
   });
 
+  it("keeps WhatsApp responsiveness opt-in for default lint selection", async () => {
+    const contributionChecks = await resolveDoctorContributionHealthChecks();
+    const whatsappCheck = contributionChecks.find(
+      (check) => check.id === "core/doctor/whatsapp-responsiveness",
+    );
+    expect(whatsappCheck).toMatchObject({ defaultEnabled: false });
+    expect(whatsappCheck).toBeDefined();
+
+    const ctx = {
+      cfg: { channels: { whatsapp: { enabled: true } } },
+      mode: "lint",
+      allowExecSecretRefs: true,
+      runtime: { log: vi.fn(), error: vi.fn(), exit: vi.fn() },
+    } as const;
+    const checks = [whatsappCheck!];
+
+    await expect(runDoctorLintChecks(ctx, { checks })).resolves.toMatchObject({
+      checksRun: 0,
+      checksSkipped: 1,
+    });
+    expect(mocks.checkGatewayHealth).not.toHaveBeenCalled();
+    expect(mocks.callGateway).not.toHaveBeenCalled();
+    expect(mocks.collectWhatsappResponsivenessHealthFindings).not.toHaveBeenCalled();
+
+    const status = {
+      eventLoop: {
+        degraded: true,
+        reasons: ["event_loop_delay"],
+        intervalMs: 30_000,
+        delayP99Ms: 42,
+        delayMaxMs: 12_000,
+        utilization: 0.3,
+        cpuCoreRatio: 0.4,
+      },
+    };
+    mocks.callGateway.mockResolvedValueOnce(status);
+    mocks.collectWhatsappResponsivenessHealthFindings.mockReturnValueOnce([
+      {
+        checkId: "core/doctor/whatsapp-responsiveness",
+        severity: "warning",
+        message: "Gateway event loop is degraded while local TUI clients are running.",
+        path: "channels.whatsapp",
+        requirement: "local-tui-event-loop-pressure",
+      },
+    ]);
+
+    await expect(
+      runDoctorLintChecks(ctx, { checks, onlyIds: ["core/doctor/whatsapp-responsiveness"] }),
+    ).resolves.toMatchObject({
+      checksRun: 1,
+      checksSkipped: 0,
+      findings: [expect.objectContaining({ checkId: "core/doctor/whatsapp-responsiveness" })],
+    });
+    expect(mocks.checkGatewayHealth).not.toHaveBeenCalled();
+    expect(mocks.callGateway).toHaveBeenCalledWith({
+      method: "status",
+      params: { includeChannelSummary: false },
+      timeoutMs: 3000,
+      config: ctx.cfg,
+      deviceIdentity: null,
+    });
+    expect(mocks.collectWhatsappResponsivenessHealthFindings).toHaveBeenCalledWith({
+      cfg: ctx.cfg,
+      status,
+    });
+
+    mocks.callGateway.mockRejectedValueOnce(new Error("gateway unavailable"));
+    mocks.collectWhatsappResponsivenessHealthFindings.mockReturnValueOnce([]);
+    const error = vi.fn();
+    await expect(
+      runDoctorLintChecks(
+        {
+          ...ctx,
+          runtime: { log: vi.fn(), error, exit: vi.fn() },
+        },
+        { checks, onlyIds: ["core/doctor/whatsapp-responsiveness"] },
+      ),
+    ).resolves.toMatchObject({
+      checksRun: 1,
+      checksSkipped: 0,
+      findings: [],
+    });
+    expect(error).not.toHaveBeenCalled();
+    expect(mocks.collectWhatsappResponsivenessHealthFindings).toHaveBeenLastCalledWith({
+      cfg: ctx.cfg,
+      status: undefined,
+    });
+  });
+
+  it("skips WhatsApp responsiveness Gateway status probes for exec SecretRefs without allow-exec", async () => {
+    const contributionChecks = await resolveDoctorContributionHealthChecks();
+    const whatsappCheck = contributionChecks.find(
+      (check) => check.id === "core/doctor/whatsapp-responsiveness",
+    );
+    expect(whatsappCheck).toBeDefined();
+    mocks.gatewaySecretInputPathCanWin.mockReturnValue(true);
+    mocks.readGatewaySecretInputValue.mockReturnValue("exec-token");
+
+    const ctx = {
+      cfg: { channels: { whatsapp: { enabled: true } } },
+      mode: "lint",
+      runtime: { log: vi.fn(), error: vi.fn(), exit: vi.fn() },
+    } as const;
+    const checks = [whatsappCheck!];
+
+    await expect(
+      runDoctorLintChecks(ctx, { checks, onlyIds: ["core/doctor/whatsapp-responsiveness"] }),
+    ).resolves.toMatchObject({
+      checksRun: 1,
+      checksSkipped: 0,
+      findings: [],
+    });
+    expect(mocks.callGateway).not.toHaveBeenCalled();
+    expect(mocks.collectWhatsappResponsivenessHealthFindings).toHaveBeenCalledWith({
+      cfg: ctx.cfg,
+      status: undefined,
+    });
+  });
+
   it("keeps device pairing opt-in for default lint selection", async () => {
     const contributionChecks = await resolveDoctorContributionHealthChecks();
     const devicePairingCheck = contributionChecks.find(
diff --git a/src/flows/doctor-health-contributions.ts b/src/flows/doctor-health-contributions.ts
