fix: prevent gateway double-spawn via port probe safety net

Fixes #289

When the gateway is already running but listProcesses() fails to detect
it (e.g. the command string appears in an unexpected form), a second
spawn attempt causes 'port already in use' errors.

Add a TCP port probe (nc -z) as a safety net before spawning. If port
18789 is already listening, the gateway is definitively running — return
null to signal 'gateway is up' without a process handle. All callers
only need the gateway to be reachable; none use the returned Process
object.

This avoids the bug in #293 where the port-check fallback tried to
return an arbitrary running process from listProcesses(), which could
be a completely unrelated process (rclone sync, shell session, etc.),
and fell through to spawn on no match — defeating the safety net.

Author: Metamolty

src/gateway/process.test.ts

@@ -1,7 +1,8 @@
 import { describe, it, expect, vi } from 'vitest';
 import { findExistingGatewayProcess } from './process';
+import { findExistingGatewayProcess, isGatewayPortOpen } from './process';
 import type { Sandbox, Process } from '@cloudflare/sandbox';
-import { createMockSandbox } from '../test-utils';
+import { createMockSandbox, createMockExecResult } from '../test-utils';
 
 function createFullMockProcess(overrides: Partial<Process> = {}): Process {
   return {
@@ -143,3 +144,29 @@ describe('findExistingGatewayProcess', () => {
     expect(result).toBeNull();
   });
 });
+
+describe('isGatewayPortOpen', () => {
+  it('returns true when port is open (nc exits 0)', async () => {
+    const { sandbox, execMock } = createMockSandbox();
+    execMock.mockResolvedValue(createMockExecResult('', { exitCode: 0 }));
+
+    const result = await isGatewayPortOpen(sandbox);
+    expect(result).toBe(true);
+    expect(execMock).toHaveBeenCalledWith('nc -z localhost 18789');
+  });
+
+  it('returns false when port is closed (nc exits non-zero)', async () => {
+    const { sandbox, execMock } = createMockSandbox();
+    execMock.mockResolvedValue(createMockExecResult('', { exitCode: 1 }));
+
+    const result = await isGatewayPortOpen(sandbox);
+    expect(result).toBe(false);
+  });
+
+  it('propagates errors from sandbox.exec', async () => {
+    const { sandbox, execMock } = createMockSandbox();
+    execMock.mockRejectedValue(new Error('container not ready'));
+
+    await expect(isGatewayPortOpen(sandbox)).rejects.toThrow('container not ready');
+  });
+});

src/gateway/process.ts

@@ -3,6 +3,15 @@ import type { OpenClawEnv } from '../types';
 import { GATEWAY_PORT, STARTUP_TIMEOUT_MS } from '../config';
 import { buildEnvVars } from './env';
 
+/**
+ * Check if the gateway port is already listening via a TCP probe.
+ * Used as a safety net when listProcesses() fails to detect the gateway.
+ */
+export async function isGatewayPortOpen(sandbox: Sandbox): Promise<boolean> {
+  const result = await sandbox.exec(`nc -z localhost ${GATEWAY_PORT}`);
+  return result.exitCode === 0;
+}
+
 /**
  * Find an existing OpenClaw gateway process
  *
@@ -50,9 +59,11 @@ export async function findExistingGatewayProcess(sandbox: Sandbox): Promise<Proc
  *
  * @param sandbox - The sandbox instance
  * @param env - Worker environment bindings
- * @returns The running gateway process
+ * @returns The running gateway process, or null if the gateway is up but we
+ *          don't have a process handle (detected via port probe only)
  */
 export async function ensureGateway(sandbox: Sandbox, env: OpenClawEnv): Promise<Process> {
+export async function ensureGateway(sandbox: Sandbox, env: OpenClawEnv): Promise<Process | null> {
   // Check if gateway is already running or starting
   const existingProcess = await findExistingGatewayProcess(sandbox);
   if (existingProcess) {
@@ -83,6 +94,18 @@ export async function ensureGateway(sandbox: Sandbox, env: OpenClawEnv): Promise
     }
   }
 
+  // Safety net: the process wasn't found by listProcesses() (e.g. the command
+  // string didn't match any known pattern), but the gateway may still be running.
+  // Probe the port directly — if it's open, the gateway is up and we're done.
+  try {
+    if (await isGatewayPortOpen(sandbox)) {
+      console.log(`Port ${GATEWAY_PORT} already open — gateway running but undetected by listProcesses(), skipping spawn`);
+      return null;
+    }
+  } catch (e) {
+    console.log('Port probe failed, proceeding to start gateway:', e);
+  }
+
   // Start a new OpenClaw gateway
   console.log('Starting new OpenClaw gateway...');
   const envVars = buildEnvVars(env);