fix: improve gateway protocol mismatch diagnostics (#82908)

* fix: improve gateway protocol mismatch diagnostics

* test: cover daemon deep connection diagnostics

* fix: normalize mapped loopback gateway clients

src/cli/daemon-cli/status.gather.test.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { StaleOpenClawUpdateLaunchdJob } from "../../daemon/launchd.js";
 import { createMockGatewayService } from "../../daemon/service.test-helpers.js";
+import type { PortConnections } from "../../infra/ports.js";
 import type { GatewayRestartHandoff } from "../../infra/restart-handoff.js";
 import { captureEnv } from "../../test-utils/env.js";
 import { VERSION } from "../../version.js";
@@ -38,6 +39,12 @@ const inspectPortUsage = vi.fn(async (port: number) => ({
   listeners: [],
   hints: [],
 }));
+const inspectPortConnections = vi.fn<(port: number) => Promise<PortConnections>>(
+  async (port: number) => ({
+    port,
+    connections: [],
+  }),
+);
 const readLastGatewayErrorLine = vi.fn(async (_env?: NodeJS.ProcessEnv) => null);
 const readGatewayRestartHandoffSync = vi.fn<
   (_env?: NodeJS.ProcessEnv) => GatewayRestartHandoff | null
@@ -166,6 +173,7 @@ vi.mock("../../gateway/net.js", () => ({
 }));
 
 vi.mock("../../infra/ports.js", () => ({
+  inspectPortConnections: (port: number) => inspectPortConnections(port),
   inspectPortUsage: (port: number) => inspectPortUsage(port),
   formatPortDiagnostics: () => [],
 }));
@@ -222,6 +230,7 @@ describe("gatherDaemonStatus", () => {
     findStaleOpenClawUpdateLaunchdJobs.mockResolvedValue([]);
     loadGatewayTlsRuntime.mockClear();
     inspectGatewayRestart.mockClear();
+    inspectPortConnections.mockClear();
     readGatewayRestartHandoffSync.mockClear();
     readConfigFileSnapshotCalls.mockClear();
     loadConfigCalls.mockClear();
@@ -484,6 +493,59 @@ describe("gatherDaemonStatus", () => {
 
     expect(readGatewayRestartHandoffSync).not.toHaveBeenCalled();
     expect(findStaleOpenClawUpdateLaunchdJobs).not.toHaveBeenCalled();
+    expect(inspectPortConnections).not.toHaveBeenCalled();
+  });
+
+  it("surfaces established gateway connections during deep status", async () => {
+    inspectPortConnections.mockResolvedValueOnce({
+      port: 19001,
+      connections: [
+        {
+          pid: 4242,
+          ppid: 1,
+          command: "node",
+          commandLine: "node /tmp/newer-openclaw/dist/index.js logs --follow",
+          address: "TCP 127.0.0.1:50123->127.0.0.1:19001 (ESTABLISHED)",
+          direction: "client",
+        },
+      ],
+    });
+
+    const status = await gatherDaemonStatus({
+      rpc: {},
+      probe: false,
+      deep: true,
+    });
+
+    expect(inspectPortConnections).toHaveBeenCalledWith(19001);
+    expect(status.connections?.established).toEqual([
+      {
+        pid: 4242,
+        ppid: 1,
+        command: "node",
+        commandLine: "node /tmp/newer-openclaw/dist/index.js logs --follow",
+        address: "TCP 127.0.0.1:50123->127.0.0.1:19001 (ESTABLISHED)",
+        direction: "client",
+      },
+    ]);
+  });
+
+  it("skips established gateway connection scans for remote gateway status", async () => {
+    daemonLoadedConfig = {
+      gateway: {
+        mode: "remote",
+        remote: { url: "wss://gateway.example" },
+      },
+    };
+
+    const status = await gatherDaemonStatus({
+      rpc: {},
+      probe: false,
+      deep: true,
+    });
+
+    expect(inspectPortConnections).not.toHaveBeenCalled();
+    expect(status.connections).toBeUndefined();
   });
 
   it("uses the fast config path for plain same-file status reads", async () => {

src/cli/daemon-cli/status.gather.ts

@@ -26,7 +26,9 @@ import {
 import { parseStrictPositiveInteger } from "../../infra/parse-finite-number.js";
 import {
   formatPortDiagnostics,
+  inspectPortConnections,
   inspectPortUsage,
+  type PortConnection,
   type PortListener,
   type PortUsageStatus,
 } from "../../infra/ports.js";
@@ -294,6 +296,10 @@ export type DaemonStatus = {
     listeners: PortListener[];
     hints: string[];
   };
+  connections?: {
+    port: number;
+    established: PortConnection[];
+  };
   lastError?: string;
   rpc?: {
     ok: boolean;
@@ -460,6 +466,27 @@ async function inspectDaemonPortStatuses(params: {
   };
 }
 
+async function inspectEstablishedGatewayClients(params: {
+  daemonPort: number;
+  deep?: boolean;
+  gatewayMode?: string;
+}): Promise<DaemonStatus["connections"] | undefined> {
+  if (params.deep !== true || params.gatewayMode === "remote") {
+    return undefined;
+  }
+  const result = await inspectPortConnections(params.daemonPort).catch(() => null);
+  const establishedClients = result?.connections.filter(
+    (connection) => connection.direction !== "server",
+  );
+  if (!result || !establishedClients || establishedClients.length === 0) {
+    return undefined;
+  }
+  return {
+    port: result.port,
+    established: establishedClients,
+  };
+}
+
 export async function gatherDaemonStatus(
   opts: {
     rpc: GatewayRpcOpts;
@@ -508,6 +535,11 @@ export async function gatherDaemonStatus(
     daemonPort,
     cliPort,
   });
+  const establishedClients = await inspectEstablishedGatewayClients({
+    daemonPort,
+    deep: opts.deep,
+    gatewayMode: daemonCfg.gateway?.mode,
+  });
 
   const extraServices = opts.deep
     ? await loadDaemonInspectModule()
@@ -618,6 +650,7 @@ export async function gatherDaemonStatus(
     gateway,
     port: portStatus,
     ...(portCliStatus ? { portCli: portCliStatus } : {}),
+    ...(establishedClients ? { connections: establishedClients } : {}),
     lastError,
     ...(rpc
       ? {

src/cli/daemon-cli/status.print.test.ts

@@ -131,6 +131,48 @@ describe("printDaemonStatus", () => {
     expectMockLineContains(runtime.error, formatCliCommand("openclaw gateway restart"));
   });
 
+  it("prints established gateway client guidance gathered by deep status", () => {
+    printDaemonStatus(
+      {
+        service: {
+          label: "LaunchAgent",
+          loaded: true,
+          loadedText: "loaded",
+          notLoadedText: "not loaded",
+          runtime: { status: "running", pid: 8000 },
+        },
+        gateway: {
+          bindMode: "loopback",
+          bindHost: "127.0.0.1",
+          port: 18789,
+          portSource: "env/config",
+          probeUrl: "ws://127.0.0.1:18789",
+        },
+        connections: {
+          port: 18789,
+          established: [
+            {
+              pid: 4242,
+              ppid: 1,
+              command: "node",
+              commandLine: "/tmp/newer-openclaw/bin/openclaw logs --follow",
+              address: "TCP 127.0.0.1:50123->127.0.0.1:18789 (ESTABLISHED)",
+              direction: "client",
+            },
+          ],
+        },
+        extraServices: [],
+      },
+      { json: false },
+    );
+
+    expectMockLineContains(runtime.log, "Established clients: 1");
+    expectMockLineContains(runtime.log, "pid=4242");
+    expectMockLineContains(runtime.log, "newer-openclaw");
+    expectMockLineContains(runtime.log, "client");
+    expectMockLineContains(runtime.log, "protocol mismatch after rollback");
+  });
+
   it("prints stale updater launchd job guidance", () => {
     printDaemonStatus(
       {

src/cli/daemon-cli/status.print.ts

@@ -72,6 +72,20 @@ function formatCliVersionLine(cli: DaemonStatus["cli"]): string | null {
   return cli.entrypoint ? `${cli.version} (${shortenHomePath(cli.entrypoint)})` : cli.version;
 }
 
+function formatConnectionLine(
+  connection: NonNullable<DaemonStatus["connections"]>["established"][number],
+) {
+  const pid = connection.pid ? `pid=${connection.pid}` : "pid=?";
+  const ppid = connection.ppid ? ` ppid=${connection.ppid}` : "";
+  const direction = ` ${connection.direction}`;
+  const command = connection.command ? ` ${connection.command}` : "";
+  const address = connection.address ? ` ${connection.address}` : "";
+  const commandLine = connection.commandLine
+    ? ` cmd=${shortenHomePath(connection.commandLine)}`
+    : "";
+  return `${pid}${ppid}${direction}${command}${address}${commandLine}`;
+}
+
 export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean }) {
   if (opts.json) {
     const sanitized = sanitizeDaemonStatusForJson(status);
@@ -285,6 +299,26 @@ export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean })
     spacer();
   }
 
+  if (status.connections?.established.length) {
+    defaultRuntime.log(
+      `${label("Established clients:")} ${infoText(String(status.connections.established.length))}`,
+    );
+    for (const connection of status.connections.established.slice(0, 8)) {
+      defaultRuntime.log(`  ${infoText(formatConnectionLine(connection))}`);
+    }
+    if (status.connections.established.length > 8) {
+      defaultRuntime.log(
+        `  ${infoText(`... ${status.connections.established.length - 8} more connection(s)`)}`,
+      );
+    }
+    defaultRuntime.log(
+      warnText(
+        "If logs show protocol mismatch after rollback, stop stale OpenClaw client processes listed here and re-run gateway status.",
+      ),
+    );
+    spacer();
+  }
+
   const systemdUnavailable =
     process.platform === "linux" && isSystemdUnavailableDetail(service.runtime?.detail);
   if (systemdUnavailable) {