agent-relay 3.1.10 → 3.1.12

package/packages/openclaw/dist/gateway.js

@@ -1,12 +1,88 @@
-import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from 'node:crypto';
 import { chmod, readFile, rename, writeFile, mkdir } from 'node:fs/promises';
-import { createServer } from 'node:http';
+import { createServer, } from 'node:http';
 import { join } from 'node:path';
 import { RelayCast } from '@relaycast/sdk';
 import WebSocket from 'ws';
 import { openclawHome } from './config.js';
-import { DEFAULT_OPENCLAW_GATEWAY_PORT } from './types.js';
+import { DEFAULT_OPENCLAW_GATEWAY_PORT, } from './types.js';
 import { SpawnManager } from './spawn/manager.js';
+const DEFAULT_POLL_ENDPOINT_PATH = '/messages/poll';
+const DEFAULT_POLL_INITIAL_CURSOR = '0';
+const DEFAULT_WS_FAILURE_THRESHOLD = 3;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 25;
+const MAX_POLL_TIMEOUT_SECONDS = 30;
+const DEFAULT_POLL_LIMIT = 100;
+const MAX_POLL_LIMIT = 500;
+const DEFAULT_WS_PROBE_INTERVAL_MS = 60_000;
+const DEFAULT_WS_STABLE_GRACE_MS = 10_000;
+const POLL_CURSOR_RECENT_EVENT_LIMIT = 256;
+const MAX_POLL_CURSOR_LENGTH = 4_096;
+const MAX_EVENT_ID_LENGTH = 512;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 30_000;
+function pollCursorStatePath() {
+    return join(openclawHome(), 'workspace', 'relaycast', 'inbound-cursor.json');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function applyJitter(ms) {
+    const factor = 1.1 + Math.random() * 0.1;
+    return Math.max(0, Math.floor(ms * factor));
+}
+function hasControlCharacters(value) {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if ((code >= 0 && code <= 31) || code === 127) {
+            return true;
+        }
+    }
+    return false;
+}
+function stripControlChars(value) {
+    let out = '';
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        out += code <= 31 || code === 127 ? ' ' : char;
+    }
+    return out;
+}
+function sanitizeOpaqueStateValue(value, maxLength) {
+    if (typeof value !== 'string')
+        return null;
+    if (value.trim().length === 0 || value.length > maxLength)
+        return null;
+    if (hasControlCharacters(value))
+        return null;
+    return value;
+}
+function computeBackoffMs(attempt) {
+    const base = Math.min(BACKOFF_BASE_MS * Math.pow(2, Math.max(0, attempt - 1)), BACKOFF_CAP_MS);
+    return applyJitter(base);
+}
+function sanitizePollTimeoutSeconds(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_POLL_TIMEOUT_SECONDS;
+    return Math.min(MAX_POLL_TIMEOUT_SECONDS, Math.max(0, Math.floor(value)));
+}
+function sanitizePollLimit(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_POLL_LIMIT;
+    return Math.min(MAX_POLL_LIMIT, Math.max(1, Math.floor(value)));
+}
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return null;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, Math.floor(seconds * 1000));
+    }
+    const asDate = Date.parse(retryAfter);
+    if (Number.isNaN(asDate))
+        return null;
+    return Math.max(0, asDate - Date.now());
+}
 function normalizeChannelName(channel) {
     return channel.startsWith('#') ? channel.slice(1) : channel;
 }
@@ -44,7 +120,10 @@ function resolveAuthProfile() {
     //    which checks valid parseable config files, not just directory existence.
     //    Strict suffix check avoids false positives from substring matching.
     const home = openclawHome();
-    const homeSuffix = home.replace(/[/\\]+$/, '').split(/[/\\]/).pop() ?? '';
+    const homeSuffix = home
+        .replace(/[/\\]+$/, '')
+        .split(/[/\\]/)
+        .pop() ?? '';
     if (homeSuffix === '.clawdbot' || homeSuffix === 'clawdbot') {
         return AUTH_PROFILES['clawdbot-v1'];
     }
@@ -167,22 +246,69 @@ function buildCanonicalVariants(device, params) {
         // V0: current default order (v3|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce|platform|deviceFamily)
         {
             name: 'v3-default-ms',
-            payload: ['v3', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtMs, params.token || '', params.nonce, params.platform, params.deviceFamily].join('|'),
+            payload: [
+                'v3',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtMs,
+                params.token || '',
+                params.nonce,
+                params.platform,
+                params.deviceFamily,
+            ].join('|'),
         },
         // V1: signedAt in seconds instead of milliseconds
         {
             name: 'v3-default-sec',
-            payload: ['v3', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtSec, params.token || '', params.nonce, params.platform, params.deviceFamily].join('|'),
+            payload: [
+                'v3',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtSec,
+                params.token || '',
+                params.nonce,
+                params.platform,
+                params.deviceFamily,
+            ].join('|'),
         },
         // V2: no token in payload (token omitted entirely)
         {
             name: 'v3-no-token-ms',
-            payload: ['v3', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtMs, params.nonce, params.platform, params.deviceFamily].join('|'),
+            payload: [
+                'v3',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtMs,
+                params.nonce,
+                params.platform,
+                params.deviceFamily,
+            ].join('|'),
         },
         // V3: nonce before token (swapped positions)
         {
             name: 'v3-nonce-first-ms',
-            payload: ['v3', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtMs, params.nonce, params.token || '', params.platform, params.deviceFamily].join('|'),
+            payload: [
+                'v3',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtMs,
+                params.nonce,
+                params.token || '',
+                params.platform,
+                params.deviceFamily,
+            ].join('|'),
         },
         // V4: fewer fields — just core identity + nonce + signedAt (minimal)
         {
@@ -192,22 +318,62 @@ function buildCanonicalVariants(device, params) {
         // V5: signedAt seconds + no token
         {
             name: 'v3-no-token-sec',
-            payload: ['v3', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtSec, params.nonce, params.platform, params.deviceFamily].join('|'),
+            payload: [
+                'v3',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtSec,
+                params.nonce,
+                params.platform,
+                params.deviceFamily,
+            ].join('|'),
         },
         // V6: v2 format (no platform/deviceFamily) — used by older gateway versions
         {
             name: 'v2-default-ms',
-            payload: ['v2', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtMs, params.token || '', params.nonce].join('|'),
+            payload: [
+                'v2',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtMs,
+                params.token || '',
+                params.nonce,
+            ].join('|'),
         },
         // V7: v2 with signedAt in seconds
         {
             name: 'v2-default-sec',
-            payload: ['v2', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtSec, params.token || '', params.nonce].join('|'),
+            payload: [
+                'v2',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtSec,
+                params.token || '',
+                params.nonce,
+            ].join('|'),
         },
         // V8: v2 without token
         {
             name: 'v2-no-token-ms',
-            payload: ['v2', device.deviceId, params.clientId, params.clientMode, params.role, scopesCsv, signedAtMs, params.nonce].join('|'),
+            payload: [
+                'v2',
+                device.deviceId,
+                params.clientId,
+                params.clientMode,
+                params.role,
+                scopesCsv,
+                signedAtMs,
+                params.nonce,
+            ].join('|'),
         },
     ];
 }
@@ -229,7 +395,7 @@ function signConnectPayload(device, params, versionOverride) {
     else {
         primaryName = profile.name === 'clawdbot-v1' ? 'v2-default-ms' : 'v3-default-ms';
     }
-    const primary = variants.find(v => v.name === primaryName) ?? variants[0];
+    const primary = variants.find((v) => v.name === primaryName) ?? variants[0];
     const payloadBytes = Buffer.from(primary.payload, 'utf-8');
     const isDebug = process.env.RELAY_LOG_LEVEL === 'DEBUG' || process.env.OPENCLAW_WS_DEBUG === '1';
     // Concise production log — one line with essential info
@@ -371,6 +537,9 @@ export class OpenClawGatewayClient {
             console.log('[openclaw-ws] Connected to OpenClaw gateway');
         });
         ws.on('message', (data) => {
+            // Guard: ignore messages from superseded WebSocket instances.
+            if (this.ws !== ws)
+                return;
             this.handleMessage(data.toString());
         });
         ws.on('close', (code, reason) => {
@@ -378,7 +547,8 @@ export class OpenClawGatewayClient {
             // During v3↔v2 fallback, the old WS is replaced before its close fires.
             if (this.ws !== ws)
                 return;
-            const reasonStr = reason.toString();
+            // Sanitize reason to prevent log injection (newlines, control chars)
+            const reasonStr = stripControlChars(reason.toString()).slice(0, 200);
             console.warn(`[openclaw-ws] Disconnected: ${code} ${reasonStr}`);
             const wasAuthenticated = this.authenticated;
             this.authenticated = false;
@@ -421,6 +591,7 @@ export class OpenClawGatewayClient {
             }
         });
     }
+    // eslint-disable-next-line complexity
     handleMessage(raw) {
         let msg;
         try {
@@ -501,8 +672,7 @@ export class OpenClawGatewayClient {
         if (msg.type === 'res' && msg.id === 'connect-1') {
             if (msg.ok) {
                 this.clearConnectTimeout();
-                const versionUsed = this.payloadVersionOverride
-                    ?? (resolveAuthProfile().name === 'clawdbot-v1' ? 'v2' : 'v3');
+                const versionUsed = this.payloadVersionOverride ?? (resolveAuthProfile().name === 'clawdbot-v1' ? 'v2' : 'v3');
                 console.log(`[openclaw-ws] Authenticated successfully (payload=${versionUsed}${this.fallbackAttempted ? ', via fallback' : ''})`);
                 this.authenticated = true;
                 this.consecutiveFailures = 0;
@@ -523,9 +693,7 @@ export class OpenClawGatewayClient {
                         console.error(`[openclaw-ws] Approve this device:  openclaw devices approve ${requestId}`);
                     }
                     console.error(`[openclaw-ws] Device ID: ${this.device.deviceId.slice(0, 16)}...`);
-                    const configHint = getWsAuthCompat() === 'clawdbot'
-                        ? '~/.clawdbot/clawdbot.json'
-                        : '~/.openclaw/openclaw.json';
+                    const configHint = getWsAuthCompat() === 'clawdbot' ? '~/.clawdbot/clawdbot.json' : '~/.openclaw/openclaw.json';
                     console.error(`[openclaw-ws] Ensure OPENCLAW_GATEWAY_TOKEN matches ${configHint} gateway.auth.token`);
                     this.pairingRejected = true;
                 }
@@ -535,8 +703,7 @@ export class OpenClawGatewayClient {
                     this.authRejectCount++;
                     this.authFallbackCount++;
                     const profile = resolveAuthProfile();
-                    const currentVersion = this.payloadVersionOverride
-                        ?? (profile.name === 'clawdbot-v1' ? 'v2' : 'v3');
+                    const currentVersion = this.payloadVersionOverride ?? (profile.name === 'clawdbot-v1' ? 'v2' : 'v3');
                     const fallbackVersion = currentVersion === 'v2' ? 'v3' : 'v2';
                     console.warn(`[ws-auth] Signature rejected with ${currentVersion} payload — retrying with ${fallbackVersion} fallback (rejects=${this.authRejectCount} fallbacks=${this.authFallbackCount})`);
                     this.payloadVersionOverride = fallbackVersion;
@@ -547,7 +714,9 @@ export class OpenClawGatewayClient {
                     try {
                         this.ws?.close();
                     }
-                    catch { }
+                    catch {
+                        // Best effort
+                    }
                     this.ws = null;
                     setTimeout(() => this.doConnect(), 0);
                     return; // Don't reject the connect promise yet — fallback attempt in progress
@@ -570,12 +739,11 @@ export class OpenClawGatewayClient {
             clearTimeout(pending.timer);
             this.pendingRpcs.delete(id);
             if (msg.ok === false || msg.error) {
-                console.warn(`[openclaw-ws] RPC ${id} error: ${JSON.stringify(msg.error ?? msg)}`);
+                console.warn('[openclaw-ws] RPC error response received');
                 pending.resolve(false);
             }
             else {
-                const result = msg.payload;
-                console.log(`[openclaw-ws] RPC ${id} ok: runId=${result?.runId ?? 'n/a'} status=${result?.status ?? 'n/a'}`);
+                console.log('[openclaw-ws] RPC succeeded');
                 pending.resolve(true);
             }
             return;
@@ -641,6 +809,9 @@ export class OpenClawGatewayClient {
             this.reconnectTimer = setTimeout(() => {
                 this.reconnectTimer = null;
                 this.pairingRejected = false; // Clear flag so connect attempt proceeds
+                // Reset fallback state so reconnect tries primary payload version first
+                this.payloadVersionOverride = null;
+                this.fallbackAttempted = false;
                 this.doConnect();
             }, OpenClawGatewayClient.PAIRING_RETRY_MS);
             return;
@@ -650,6 +821,9 @@ export class OpenClawGatewayClient {
         console.log(`[openclaw-ws] Reconnecting in ${delay / 1000}s (attempt ${this.consecutiveFailures})...`);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
+            // Reset fallback state so reconnect tries primary payload version first
+            this.payloadVersionOverride = null;
+            this.fallbackAttempted = false;
             this.doConnect();
         }, delay);
     }
@@ -669,7 +843,9 @@ export class OpenClawGatewayClient {
             try {
                 this.ws.close();
             }
-            catch { }
+            catch {
+                // Best effort
+            }
             this.ws = null;
         }
         this.authenticated = false;
@@ -684,6 +860,7 @@ export class OpenClawGatewayClient {
 export class InboundGateway {
     relaySender;
     relayAgentClient = null;
+    relayAgentToken = null;
     relaycast;
     config;
     dedupeTtlMs;
@@ -699,6 +876,25 @@ export class InboundGateway {
     controlServer = null;
     /** Port the control server listens on. */
     controlPort = 0;
+    transportState = 'WS_DEGRADED';
+    activeTransportMode = 'ws';
+    wsFailureCount = 0;
+    pollLoopPromise = null;
+    pollAbortController = null;
+    pollLoopStopRequested = false;
+    pollCursorLoaded = false;
+    pollCursor = DEFAULT_POLL_INITIAL_CURSOR;
+    pollLastSequence = 0;
+    pollRecentEventIds = [];
+    pollFailureCount = 0;
+    probeWsTimer = null;
+    wsRecoveryTimer = null;
+    fallbackCount = 0;
+    lastFallbackReason = null;
+    fallbackStartedAt = null;
+    totalFallbackMs = 0;
+    duplicateDropCount = 0;
+    cursorResetCount = 0;
     /** Default control port for the gateway's spawn API. */
     static DEFAULT_CONTROL_PORT = 18790;
     constructor(options) {
@@ -712,92 +908,578 @@ export class InboundGateway {
             baseUrl: this.config.baseUrl,
         });
         const dedupeTtlMs = Number(process.env.RELAYCAST_DEDUPE_TTL_MS ?? 15 * 60 * 1000);
-        this.dedupeTtlMs = Number.isFinite(dedupeTtlMs) && dedupeTtlMs >= 1000
-            ? Math.floor(dedupeTtlMs)
-            : 15 * 60 * 1000;
+        this.dedupeTtlMs =
+            Number.isFinite(dedupeTtlMs) && dedupeTtlMs >= 1000 ? Math.floor(dedupeTtlMs) : 15 * 60 * 1000;
         const parentDepth = Number(process.env.OPENCLAW_SPAWN_DEPTH || 0);
         this.spawnManager = new SpawnManager({ spawnDepth: parentDepth + 1 });
     }
-    /** Start the gateway — register agent and subscribe for realtime events. */
-    async start() {
-        if (this.running)
-            return;
-        this.running = true;
-        // Connect to the local OpenClaw gateway WebSocket (persistent connection)
-        const token = this.config.openclawGatewayToken ?? process.env.OPENCLAW_GATEWAY_TOKEN;
-        const port = this.config.openclawGatewayPort ?? DEFAULT_OPENCLAW_GATEWAY_PORT;
-        if (token) {
-            this.openclawClient = await OpenClawGatewayClient.create(token, port);
+    isPollFallbackEnabled() {
+        return this.config.transport?.pollFallback?.enabled ?? false;
+    }
+    wsFailureThreshold() {
+        const configured = this.config.transport?.pollFallback?.wsFailureThreshold;
+        if (!Number.isFinite(configured) || configured === undefined) {
+            return DEFAULT_WS_FAILURE_THRESHOLD;
+        }
+        return Math.max(1, Math.floor(configured));
+    }
+    pollTimeoutSeconds() {
+        return sanitizePollTimeoutSeconds(this.config.transport?.pollFallback?.timeoutSeconds);
+    }
+    pollLimit() {
+        return sanitizePollLimit(this.config.transport?.pollFallback?.limit);
+    }
+    pollInitialCursor() {
+        return this.config.transport?.pollFallback?.initialCursor?.trim() || DEFAULT_POLL_INITIAL_CURSOR;
+    }
+    isWsProbeEnabled() {
+        return this.config.transport?.pollFallback?.probeWs?.enabled ?? true;
+    }
+    wsProbeIntervalMs() {
+        const configured = this.config.transport?.pollFallback?.probeWs?.intervalMs;
+        if (!Number.isFinite(configured) || configured === undefined) {
+            return DEFAULT_WS_PROBE_INTERVAL_MS;
+        }
+        return Math.max(1_000, Math.floor(configured));
+    }
+    wsStableGraceMs() {
+        const configured = this.config.transport?.pollFallback?.probeWs?.stableGraceMs;
+        if (!Number.isFinite(configured) || configured === undefined) {
+            return DEFAULT_WS_STABLE_GRACE_MS;
+        }
+        return Math.max(1_000, Math.floor(configured));
+    }
+    transportHealthSnapshot() {
+        const activeFallbackMs = this.fallbackStartedAt === null ? 0 : Date.now() - this.fallbackStartedAt;
+        return {
+            mode: this.activeTransportMode,
+            state: this.transportState,
+            wsFailureCount: this.wsFailureCount,
+            fallbackCount: this.fallbackCount,
+            lastFallbackReason: this.lastFallbackReason,
+            timeInFallbackMs: this.totalFallbackMs + activeFallbackMs,
+            duplicateDrops: this.duplicateDropCount,
+            cursorResets: this.cursorResetCount,
+            lastSequence: this.pollLastSequence,
+        };
+    }
+    completeFallbackWindow() {
+        if (this.fallbackStartedAt !== null) {
+            this.totalFallbackMs += Date.now() - this.fallbackStartedAt;
+            this.fallbackStartedAt = null;
+        }
+    }
+    cleanupRelaySubscriptions() {
+        for (const unsubscribe of this.unsubscribeHandlers) {
             try {
-                await this.openclawClient.connect();
-                console.log('[gateway] OpenClaw gateway WebSocket client ready');
+                unsubscribe();
             }
-            catch (err) {
-                console.warn(`[gateway] OpenClaw gateway WS failed (will retry per message): ${err instanceof Error ? err.message : String(err)}`);
+            catch {
+                // Best effort
             }
         }
-        else {
-            console.warn('[gateway] No OPENCLAW_GATEWAY_TOKEN — local delivery disabled');
+        this.unsubscribeHandlers = [];
+    }
+    subscribeRelayChannels() {
+        if (!this.relayAgentClient)
+            return;
+        try {
+            this.relayAgentClient.subscribe(this.config.channels);
         }
-        const registered = await this.relaycast.agents.registerOrGet({
-            name: this.config.clawName,
-            type: 'agent',
-            persona: 'Relaycast inbound gateway for OpenClaw',
-        });
-        this.relayAgentClient = this.relaycast.as(registered.token);
-        // Connect first, then register handlers. The SDK requires connect()
-        // before subscribe() can be called.
-        this.relayAgentClient.connect();
+        catch {
+            // Will subscribe on the next connected event.
+        }
+    }
+    async connectRelayAgentClient() {
+        if (!this.relayAgentClient)
+            return;
+        try {
+            await Promise.resolve(this.relayAgentClient.connect());
+        }
+        catch (error) {
+            console.warn(`[gateway] Relaycast WS connect failed: ${error instanceof Error ? error.message : String(error)}`);
+            await this.handleWsFailure('connect_failed');
+        }
+    }
+    bindRelayAgentHandlers() {
+        if (!this.relayAgentClient)
+            return;
+        this.cleanupRelaySubscriptions();
         this.unsubscribeHandlers.push(this.relayAgentClient.on.connected(() => {
             console.log(`[gateway] Relaycast WebSocket connected, subscribing to channels: ${this.config.channels.join(', ')}`);
-            this.relayAgentClient?.subscribe(this.config.channels);
+            this.wsFailureCount = 0;
+            this.subscribeRelayChannels();
+            if (this.transportState === 'POLL_ACTIVE' || this.transportState === 'RECOVERING_WS') {
+                this.beginWsRecovery();
+                return;
+            }
+            this.completeFallbackWindow();
+            this.transportState = 'WS_ACTIVE';
+            this.activeTransportMode = 'ws';
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.messageCreated((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Realtime message from @${event.message?.agentName} in #${event.channel}`);
             void this.handleRealtimeMessage(event);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.threadReply((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Thread reply from @${event.message?.agentName} in #${event.channel} (parent: ${event.parentId})`);
             void this.handleRealtimeThreadReply(event);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.dmReceived((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] DM from @${event.message?.agentName} (conv: ${event.conversationId})`);
             void this.handleRealtimeDm(event);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.groupDmReceived((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Group DM from @${event.message?.agentName} (conv: ${event.conversationId})`);
             void this.handleRealtimeGroupDm(event);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.commandInvoked((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Command /${event.command} invoked by @${event.invokedBy} in #${event.channel}`);
             void this.handleRealtimeCommand(event);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.reactionAdded((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Reaction :${event.emoji}: added by @${event.agentName} on ${event.messageId}`);
             void this.handleRealtimeReaction(event, 'added');
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.reactionRemoved((event) => {
+            if (!this.shouldProcessWsInbound())
+                return;
             console.log(`[gateway] Reaction :${event.emoji}: removed by @${event.agentName} from ${event.messageId}`);
             void this.handleRealtimeReaction(event, 'removed');
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.reconnecting((attempt) => {
             console.warn(`[gateway] Relaycast reconnecting (attempt ${attempt})`);
+            void this.handleWsFailure(`reconnecting:${attempt}`);
         }));
         this.unsubscribeHandlers.push(this.relayAgentClient.on.disconnected(() => {
-            console.warn(`[gateway] Relaycast disconnected`);
+            console.warn('[gateway] Relaycast disconnected');
+            void this.handleWsFailure('disconnected');
         }));
-        this.unsubscribeHandlers.push(this.relayAgentClient.on.error(() => {
-            console.warn(`[gateway] Relaycast socket error`);
+        this.unsubscribeHandlers.push(this.relayAgentClient.on.error((error) => {
+            const message = error instanceof Error ? error.message : 'socket error';
+            console.warn(`[gateway] Relaycast socket error${message ? `: ${message}` : ''}`);
+            void this.handleWsFailure(message || 'socket_error');
         }));
+    }
+    async replaceRelayAgentClient(agentToken) {
+        this.cleanupRelaySubscriptions();
+        if (this.relayAgentClient) {
+            try {
+                await this.relayAgentClient.disconnect();
+            }
+            catch {
+                // Best effort
+            }
+        }
+        this.relayAgentToken = agentToken;
+        this.relayAgentClient = this.relaycast.as(agentToken);
+        this.bindRelayAgentHandlers();
+        await this.connectRelayAgentClient();
+    }
+    async refreshRelayAgentRegistration() {
+        const registered = await this.relaycast.agents.registerOrRotate({
+            name: this.config.clawName,
+            type: 'agent',
+            persona: 'Relaycast inbound gateway for OpenClaw',
+        });
+        await this.replaceRelayAgentClient(registered.token);
         await this.ensureChannelMembership();
-        // Also subscribe explicitly in case the `connected` event already fired
-        // before we registered the handler above.
+        this.subscribeRelayChannels();
+    }
+    shouldProcessWsInbound() {
+        return (!this.isPollFallbackEnabled() ||
+            this.transportState === 'WS_ACTIVE' ||
+            this.transportState === 'RECOVERING_WS');
+    }
+    async handleWsFailure(reason) {
+        if (!this.running)
+            return;
+        if (this.wsRecoveryTimer) {
+            clearTimeout(this.wsRecoveryTimer);
+            this.wsRecoveryTimer = null;
+        }
+        if (this.transportState === 'RECOVERING_WS') {
+            console.warn(`[gateway] WS recovery probe failed, remaining on long-poll (${reason})`);
+            this.transportState = 'POLL_ACTIVE';
+            this.activeTransportMode = 'poll';
+            await this.startPollLoop();
+            this.startWsProbeLoop();
+            return;
+        }
+        if (this.transportState === 'POLL_ACTIVE') {
+            this.lastFallbackReason = reason;
+            return;
+        }
+        this.transportState = 'WS_DEGRADED';
+        this.wsFailureCount += 1;
+        if (this.isPollFallbackEnabled() && this.wsFailureCount >= this.wsFailureThreshold()) {
+            await this.activatePollFallback(reason);
+        }
+    }
+    async activatePollFallback(reason) {
+        if (!this.running || !this.isPollFallbackEnabled())
+            return;
+        if (this.transportState === 'POLL_ACTIVE')
+            return;
+        await this.ensurePollCursorLoaded();
+        this.transportState = 'POLL_ACTIVE';
+        this.activeTransportMode = 'poll';
+        this.fallbackCount += 1;
+        this.lastFallbackReason = reason;
+        if (this.fallbackStartedAt === null) {
+            this.fallbackStartedAt = Date.now();
+        }
+        console.warn(`[gateway] Realtime degraded: using long-poll fallback (${reason})`);
+        await this.startPollLoop();
+        this.startWsProbeLoop();
+    }
+    startWsProbeLoop() {
+        if (!this.isWsProbeEnabled() || this.probeWsTimer)
+            return;
+        this.probeWsTimer = setInterval(() => {
+            if (!this.running || this.transportState !== 'POLL_ACTIVE')
+                return;
+            void this.connectRelayAgentClient();
+        }, this.wsProbeIntervalMs());
+    }
+    stopWsProbeLoop() {
+        if (!this.probeWsTimer)
+            return;
+        clearInterval(this.probeWsTimer);
+        this.probeWsTimer = null;
+    }
+    beginWsRecovery() {
+        if (!this.running)
+            return;
+        this.transportState = 'RECOVERING_WS';
+        this.stopWsProbeLoop();
+        if (this.wsRecoveryTimer) {
+            clearTimeout(this.wsRecoveryTimer);
+        }
+        console.log(`[gateway] WS probe connected, waiting ${this.wsStableGraceMs()}ms before promotion`);
+        this.wsRecoveryTimer = setTimeout(() => {
+            this.wsRecoveryTimer = null;
+            void this.promoteWsTransport();
+        }, this.wsStableGraceMs());
+    }
+    async promoteWsTransport() {
+        if (!this.running || this.transportState !== 'RECOVERING_WS')
+            return;
+        await this.stopPollLoop();
+        const catchupDelayMs = await this.pollOnce(0);
+        if (catchupDelayMs > 0) {
+            console.warn('[gateway] WS promotion catch-up poll failed, remaining on long-poll');
+            this.transportState = 'POLL_ACTIVE';
+            this.activeTransportMode = 'poll';
+            await this.startPollLoop();
+            this.startWsProbeLoop();
+            return;
+        }
+        this.completeFallbackWindow();
+        this.transportState = 'WS_ACTIVE';
+        this.activeTransportMode = 'ws';
+        this.wsFailureCount = 0;
+        console.log('[gateway] Relaycast WebSocket recovered; promoting WS to active transport');
+    }
+    async ensurePollCursorLoaded() {
+        if (this.pollCursorLoaded)
+            return;
+        this.pollCursorLoaded = true;
+        this.pollCursor = this.pollInitialCursor();
         try {
-            this.relayAgentClient.subscribe(this.config.channels);
+            const raw = await readFile(pollCursorStatePath(), 'utf-8');
+            const parsed = JSON.parse(raw);
+            const persistedCursor = sanitizeOpaqueStateValue(parsed.cursor, MAX_POLL_CURSOR_LENGTH);
+            if (persistedCursor) {
+                this.pollCursor = persistedCursor;
+            }
+            if (Number.isFinite(parsed.lastSequence)) {
+                this.pollLastSequence = Math.max(0, Math.floor(parsed.lastSequence ?? 0));
+            }
+            if (Array.isArray(parsed.recentEventIds)) {
+                this.pollRecentEventIds = parsed.recentEventIds
+                    .map((value) => sanitizeOpaqueStateValue(value, MAX_EVENT_ID_LENGTH))
+                    .filter((value) => value !== null)
+                    .slice(-POLL_CURSOR_RECENT_EVENT_LIMIT);
+                const now = Date.now();
+                for (const eventId of this.pollRecentEventIds) {
+                    this.seenMessageIds.set(eventId, now);
+                }
+            }
         }
-        catch {
-            // Will subscribe on next connected event
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.warn(`[gateway] Failed to load poll cursor state: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    async persistPollCursorState() {
+        const cursor = sanitizeOpaqueStateValue(this.pollCursor, MAX_POLL_CURSOR_LENGTH) ?? this.pollInitialCursor();
+        const recentEventIds = this.pollRecentEventIds
+            .map((eventId) => sanitizeOpaqueStateValue(eventId, MAX_EVENT_ID_LENGTH))
+            .filter((eventId) => eventId !== null)
+            .slice(-POLL_CURSOR_RECENT_EVENT_LIMIT);
+        this.pollCursor = cursor;
+        this.pollRecentEventIds = recentEventIds;
+        const state = {
+            cursor,
+            lastSequence: this.pollLastSequence,
+            recentEventIds,
+            updatedAt: new Date().toISOString(),
+        };
+        const filePath = pollCursorStatePath();
+        const tmpPath = `${filePath}.tmp`;
+        await mkdir(join(openclawHome(), 'workspace', 'relaycast'), { recursive: true });
+        await writeFile(tmpPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+        await rename(tmpPath, filePath);
+    }
+    rememberPollEventId(eventId) {
+        const sanitizedEventId = sanitizeOpaqueStateValue(eventId, MAX_EVENT_ID_LENGTH);
+        if (!sanitizedEventId)
+            return;
+        this.pollRecentEventIds = [
+            ...this.pollRecentEventIds.filter((id) => id !== sanitizedEventId),
+            sanitizedEventId,
+        ].slice(-POLL_CURSOR_RECENT_EVENT_LIMIT);
+    }
+    hasRecentPollEventId(eventId) {
+        return this.pollRecentEventIds.includes(eventId);
+    }
+    async commitPollCursorState(nextCursor, lastSequence) {
+        const sanitizedCursor = sanitizeOpaqueStateValue(nextCursor, MAX_POLL_CURSOR_LENGTH);
+        if (sanitizedCursor) {
+            this.pollCursor = sanitizedCursor;
+        }
+        this.pollLastSequence = Math.max(this.pollLastSequence, lastSequence);
+        await this.persistPollCursorState();
+    }
+    async resetPollCursorState(reason) {
+        this.cursorResetCount += 1;
+        this.lastFallbackReason = reason;
+        this.pollCursor = this.pollInitialCursor();
+        this.pollLastSequence = 0;
+        await this.persistPollCursorState();
+    }
+    async startPollLoop() {
+        if (this.pollLoopPromise)
+            return;
+        this.pollLoopStopRequested = false;
+        this.pollLoopPromise = (async () => {
+            while (this.running &&
+                !this.pollLoopStopRequested &&
+                (this.transportState === 'POLL_ACTIVE' || this.transportState === 'RECOVERING_WS')) {
+                const delayMs = await this.pollOnce(this.pollTimeoutSeconds());
+                if (!this.running ||
+                    this.pollLoopStopRequested ||
+                    !(this.transportState === 'POLL_ACTIVE' || this.transportState === 'RECOVERING_WS')) {
+                    break;
+                }
+                if (delayMs > 0) {
+                    await sleep(delayMs);
+                }
+            }
+        })().finally(() => {
+            this.pollLoopPromise = null;
+            this.pollAbortController = null;
+        });
+    }
+    async stopPollLoop() {
+        this.pollLoopStopRequested = true;
+        if (this.pollAbortController) {
+            this.pollAbortController.abort();
+            this.pollAbortController = null;
+        }
+        if (this.pollLoopPromise) {
+            await this.pollLoopPromise.catch(() => undefined);
+            this.pollLoopPromise = null;
+        }
+    }
+    // eslint-disable-next-line complexity
+    async pollOnce(timeoutSeconds) {
+        await this.ensurePollCursorLoaded();
+        const baseUrl = new URL(DEFAULT_POLL_ENDPOINT_PATH, this.config.baseUrl);
+        baseUrl.searchParams.set('cursor', this.pollCursor);
+        baseUrl.searchParams.set('timeout', String(timeoutSeconds));
+        baseUrl.searchParams.set('limit', String(this.pollLimit()));
+        const timeoutMs = Math.max(5_000, (timeoutSeconds + 5) * 1_000);
+        const abortController = new AbortController();
+        this.pollAbortController = abortController;
+        const timeoutHandle = setTimeout(() => abortController.abort(), timeoutMs);
+        try {
+            const response = await fetch(baseUrl, {
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                    Authorization: this.relayAgentToken ? `Bearer ${this.relayAgentToken}` : '',
+                    'x-api-key': this.config.apiKey,
+                },
+                signal: abortController.signal,
+            });
+            if (response.status === 401 || response.status === 403) {
+                console.warn(`[gateway] Poll auth rejected (${response.status}); refreshing token`);
+                try {
+                    await this.refreshRelayAgentRegistration();
+                    this.pollFailureCount = 0;
+                    return 0;
+                }
+                catch (error) {
+                    console.warn(`[gateway] Poll auth refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+                    this.pollFailureCount += 1;
+                    return computeBackoffMs(this.pollFailureCount);
+                }
+            }
+            if (response.status === 409) {
+                console.warn('[gateway] Poll cursor invalid/stale; resetting cursor state');
+                this.pollFailureCount = 0;
+                await this.resetPollCursorState('cursor_reset');
+                return 0;
+            }
+            if (response.status === 429) {
+                this.pollFailureCount += 1;
+                const retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
+                return retryAfterMs !== null ? applyJitter(retryAfterMs) : computeBackoffMs(this.pollFailureCount);
+            }
+            if (response.status >= 500) {
+                this.pollFailureCount += 1;
+                return computeBackoffMs(this.pollFailureCount);
+            }
+            if (!response.ok) {
+                this.pollFailureCount += 1;
+                console.warn(`[gateway] Poll request failed: HTTP ${response.status}`);
+                return computeBackoffMs(this.pollFailureCount);
+            }
+            const body = (await response.json());
+            this.pollFailureCount = 0;
+            const processed = await this.processPollResponse(body);
+            return processed ? 0 : computeBackoffMs(1);
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                return 0;
+            }
+            this.pollFailureCount += 1;
+            console.warn(`[gateway] Poll request failed: ${error instanceof Error ? error.message : String(error)}`);
+            return computeBackoffMs(this.pollFailureCount);
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+            if (this.pollAbortController === abortController) {
+                this.pollAbortController = null;
+            }
+        }
+    }
+    async processPollResponse(body) {
+        const events = Array.isArray(body.events) ? [...body.events] : [];
+        events.sort((left, right) => left.sequence - right.sequence);
+        let lastSequence = this.pollLastSequence;
+        for (const event of events) {
+            if (!event || typeof event.id !== 'string' || !Number.isFinite(event.sequence)) {
+                continue;
+            }
+            lastSequence = Math.max(lastSequence, event.sequence);
+            if (event.sequence <= this.pollLastSequence ||
+                this.hasRecentPollEventId(event.id) ||
+                this.isSeen(event.id)) {
+                this.duplicateDropCount += 1;
+                continue;
+            }
+            const committed = await this.handlePolledEvent(event);
+            if (!committed) {
+                return false;
+            }
+            this.rememberPollEventId(event.id);
+        }
+        const nextCursor = sanitizeOpaqueStateValue(body.nextCursor, MAX_POLL_CURSOR_LENGTH) ?? this.pollCursor;
+        await this.commitPollCursorState(nextCursor, lastSequence);
+        return true;
+    }
+    // eslint-disable-next-line complexity
+    async handlePolledEvent(event) {
+        const type = typeof event.payload.type === 'string' ? event.payload.type : '';
+        const baseOptions = {
+            timestamp: event.timestamp,
+        };
+        switch (type) {
+            case 'message.created':
+            case 'message.received':
+            case 'message.new':
+            case 'message.sent':
+                return (await this.handleRealtimeMessage(event.payload, baseOptions)).committed;
+            case 'thread.reply':
+            case 'thread.message.created':
+            case 'thread.message.sent':
+                return (await this.handleRealtimeThreadReply(event.payload, baseOptions)).committed;
+            case 'dm.received':
+            case 'dm.message.created':
+            case 'direct_message.created':
+                return (await this.handleRealtimeDm(event.payload, baseOptions))
+                    .committed;
+            case 'group_dm.received':
+            case 'group_dm.message.created':
+                return (await this.handleRealtimeGroupDm(event.payload, baseOptions)).committed;
+            case 'command.invoked':
+                return (await this.handleRealtimeCommand(event.payload, {
+                    ...baseOptions,
+                    eventId: event.id,
+                })).committed;
+            case 'reaction.added':
+                return (await this.handleRealtimeReaction(event.payload, 'added', {
+                    ...baseOptions,
+                    eventId: event.id,
+                })).committed;
+            case 'reaction.removed':
+                return (await this.handleRealtimeReaction(event.payload, 'removed', {
+                    ...baseOptions,
+                    eventId: event.id,
+                })).committed;
+            default:
+                console.warn(`[gateway] Ignoring unknown polled event type: ${type || 'unknown'}`);
+                return true;
+        }
+    }
+    /** Start the gateway — register agent and subscribe for realtime events. */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Connect to the local OpenClaw gateway WebSocket (persistent connection)
+        const token = this.config.openclawGatewayToken ?? process.env.OPENCLAW_GATEWAY_TOKEN;
+        const port = this.config.openclawGatewayPort ?? DEFAULT_OPENCLAW_GATEWAY_PORT;
+        if (token) {
+            this.openclawClient = await OpenClawGatewayClient.create(token, port);
+            try {
+                await this.openclawClient.connect();
+                console.log('[gateway] OpenClaw gateway WebSocket client ready');
+            }
+            catch (err) {
+                console.warn(`[gateway] OpenClaw gateway WS failed (will retry per message): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            console.warn('[gateway] No OPENCLAW_GATEWAY_TOKEN — local delivery disabled');
         }
+        const registered = await this.relaycast.agents.registerOrGet({
+            name: this.config.clawName,
+            type: 'agent',
+            persona: 'Relaycast inbound gateway for OpenClaw',
+        });
+        await this.replaceRelayAgentClient(registered.token);
+        await this.ensureChannelMembership();
+        // Also subscribe explicitly in case the `connected` event fired before
+        // the handler ran, or the SDK defers connection readiness.
+        this.subscribeRelayChannels();
         console.log(`[gateway] Realtime listening on channels: ${this.config.channels.join(', ')}`);
         // Start spawn control HTTP server
         await this.startControlServer();
@@ -805,15 +1487,14 @@ export class InboundGateway {
     /** Stop the gateway — clean up websocket and relay clients. */
     async stop() {
         this.running = false;
-        for (const unsubscribe of this.unsubscribeHandlers) {
-            try {
-                unsubscribe();
-            }
-            catch {
-                // Best effort
-            }
+        this.stopWsProbeLoop();
+        if (this.wsRecoveryTimer) {
+            clearTimeout(this.wsRecoveryTimer);
+            this.wsRecoveryTimer = null;
         }
-        this.unsubscribeHandlers = [];
+        this.completeFallbackWindow();
+        await this.stopPollLoop();
+        this.cleanupRelaySubscriptions();
         if (this.relayAgentClient) {
             try {
                 await this.relayAgentClient.disconnect();
@@ -871,96 +1552,97 @@ export class InboundGateway {
             }
         }
     }
-    async handleRealtimeMessage(event) {
+    async handleRealtimeMessage(event, options = {}) {
         const channel = normalizeChannelName(event.channel);
         if (!this.config.channels.includes(channel))
-            return;
-        const messageId = event.message?.id;
+            return { committed: true };
+        const messageId = options.eventId ?? event.message?.id;
         if (!messageId)
-            return;
+            return { committed: true };
         const inbound = {
             id: messageId,
             channel,
-            from: event.message.agentName,
-            text: event.message.text,
-            timestamp: new Date().toISOString(),
+            from: event.message?.agentName ?? 'unknown',
+            text: event.message?.text ?? '',
+            timestamp: options.timestamp ?? new Date().toISOString(),
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleRealtimeThreadReply(event) {
+    async handleRealtimeThreadReply(event, options = {}) {
         const channel = normalizeChannelName(event.channel);
         if (!this.config.channels.includes(channel))
-            return;
-        const messageId = event.message?.id;
+            return { committed: true };
+        const messageId = options.eventId ?? event.message?.id;
         if (!messageId)
-            return;
+            return { committed: true };
         const inbound = {
             id: messageId,
             channel,
-            from: event.message.agentName,
-            text: event.message.text,
-            timestamp: new Date().toISOString(),
+            from: event.message?.agentName ?? 'unknown',
+            text: event.message?.text ?? '',
+            timestamp: options.timestamp ?? new Date().toISOString(),
             threadParentId: event.parentId,
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleRealtimeDm(event) {
-        const messageId = event.message?.id;
+    async handleRealtimeDm(event, options = {}) {
+        const messageId = options.eventId ?? event.message?.id;
         if (!messageId)
-            return;
+            return { committed: true };
         const inbound = {
             id: messageId,
             channel: 'dm',
-            from: event.message.agentName,
-            text: event.message.text,
-            timestamp: new Date().toISOString(),
+            from: event.message?.agentName ?? 'unknown',
+            text: event.message?.text ?? '',
+            timestamp: options.timestamp ?? new Date().toISOString(),
             conversationId: event.conversationId,
             kind: 'dm',
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleRealtimeGroupDm(event) {
-        const messageId = event.message?.id;
+    async handleRealtimeGroupDm(event, options = {}) {
+        const messageId = options.eventId ?? event.message?.id;
         if (!messageId)
-            return;
+            return { committed: true };
         const inbound = {
             id: messageId,
             channel: `groupdm:${event.conversationId}`,
-            from: event.message.agentName,
-            text: event.message.text,
-            timestamp: new Date().toISOString(),
+            from: event.message?.agentName ?? 'unknown',
+            text: event.message?.text ?? '',
+            timestamp: options.timestamp ?? new Date().toISOString(),
             conversationId: event.conversationId,
             kind: 'groupdm',
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleRealtimeCommand(event) {
+    async handleRealtimeCommand(event, options = {}) {
         const channel = normalizeChannelName(event.channel);
         if (!this.config.channels.includes(channel))
-            return;
+            return { committed: true };
         // Commands lack a server-assigned event ID, so we synthesize one.
         // We include args + timestamp to avoid silently dropping legitimate
         // repeat invocations (e.g. /deploy twice in 15 min). This means SDK
         // reconnection replays may deliver a duplicate, but that's less
         // harmful than silently swallowing a real command.
         const argsSlug = event.args ? `_${event.args}` : '';
-        const syntheticId = `cmd_${event.command}_${channel}_${event.invokedBy}${argsSlug}_${Date.now()}`;
+        const syntheticId = options.eventId ?? `cmd_${event.command}_${channel}_${event.invokedBy}${argsSlug}_${Date.now()}`;
         const argsText = event.args ? ` ${event.args}` : '';
         const inbound = {
             id: syntheticId,
             channel,
             from: event.invokedBy,
             text: `[relaycast:command:${channel}] @${event.invokedBy} /${event.command}${argsText}`,
-            timestamp: new Date().toISOString(),
+            timestamp: options.timestamp ?? new Date().toISOString(),
             kind: 'command',
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleRealtimeReaction(event, action) {
+    async handleRealtimeReaction(event, action, options = {}) {
         // Include timestamp so add→remove→re-add of the same emoji isn't
         // silently dropped within the 15-min dedup window. Reactions are soft
         // notifications, so a rare duplicate on SDK reconnect is acceptable.
-        const syntheticId = `reaction_${event.messageId}_${event.emoji}_${event.agentName}_${action}_${Date.now()}`;
+        const syntheticId = options.eventId ??
+            `reaction_${event.messageId}_${event.emoji}_${event.agentName}_${action}_${Date.now()}`;
         const text = action === 'added'
             ? `[relaycast:reaction] @${event.agentName} reacted ${event.emoji} to message ${event.messageId} (soft notification, no action required)`
             : `[relaycast:reaction] @${event.agentName} removed ${event.emoji} from message ${event.messageId} (soft notification, no action required)`;
@@ -969,49 +1651,57 @@ export class InboundGateway {
             channel: 'reaction',
             from: event.agentName,
             text,
-            timestamp: new Date().toISOString(),
+            timestamp: options.timestamp ?? new Date().toISOString(),
             kind: 'reaction',
         };
-        await this.handleInbound(inbound);
+        return this.processInbound(inbound);
     }
-    async handleInbound(message) {
+    async processInbound(message) {
         if (!this.running)
-            return;
-        if (this.processingMessageIds.has(message.id) || this.isSeen(message.id))
-            return;
+            return { committed: false };
+        if (this.processingMessageIds.has(message.id) || this.isSeen(message.id)) {
+            this.duplicateDropCount += 1;
+            return { committed: true, reason: 'duplicate' };
+        }
         // Avoid echo loops — skip messages from this claw.
         if (message.from === this.config.clawName) {
-            // Only update cursor for real channels with real (non-synthetic) message IDs.
             this.markSeen(message.id);
-            return;
+            return { committed: true, reason: 'echo' };
         }
-        // Mark as seen immediately to prevent duplicate delivery from concurrent
-        // realtime events processing the same message.
-        this.markSeen(message.id);
         this.processingMessageIds.add(message.id);
         console.log(`[gateway] Delivering message ${message.id} from @${message.from}: "${message.text}"`);
         try {
             const result = await this.onMessage(message);
             console.log(`[gateway] Delivery result: ${result.method} ok=${result.ok}${result.error ? ' error=' + result.error : ''}`);
+            if (!result.ok) {
+                return { committed: false, result };
+            }
+            this.markSeen(message.id);
+            return { committed: true, result };
         }
         finally {
             this.processingMessageIds.delete(message.id);
         }
     }
-    /** Format delivery text with channel, sender, and optional thread prefix. */
+    /** Format delivery text with channel, sender, and response hint. */
     formatDeliveryText(message) {
-        // Pre-formatted kinds (command, reaction) already have the full text.
-        if (message.kind === 'command' || message.kind === 'reaction') {
+        // Pre-formatted kinds (reaction) already have the full text with hints.
+        if (message.kind === 'reaction') {
             return message.text;
         }
+        if (message.kind === 'command') {
+            return `${message.text}\n(command invocation — respond with: post_message channel="${message.channel}")`;
+        }
         if (message.kind === 'dm') {
-            return `[relaycast:dm] @${message.from}: ${message.text}`;
+            return `[relaycast:dm] @${message.from}: ${message.text}\n(reply with: send_dm to="${message.from}")`;
         }
         if (message.kind === 'groupdm') {
-            return `[relaycast:groupdm] @${message.from}: ${message.text}`;
+            return `[relaycast:groupdm] @${message.from}: ${message.text}\n(reply with: send_dm to="${message.from}")`;
+        }
+        if (message.threadParentId) {
+            return `[thread] [relaycast:${message.channel}] @${message.from}: ${message.text}\n(reply with: reply_to_thread message_id="${message.threadParentId}")`;
         }
-        const threadPrefix = message.threadParentId ? '[thread] ' : '';
-        return `${threadPrefix}[relaycast:${message.channel}] @${message.from}: ${message.text}`;
+        return `[relaycast:${message.channel}] @${message.from}: ${message.text}\n(reply with: post_message channel="${message.channel}" or reply_to_thread message_id="${message.id}")`;
     }
     /** Handle an inbound Relaycast message. */
     async onMessage(message) {
@@ -1076,6 +1766,7 @@ export class InboundGateway {
             });
         });
     }
+    // eslint-disable-next-line complexity
     async handleControlRequest(req, res) {
         const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
         const path = url.pathname;
@@ -1088,6 +1779,7 @@ export class InboundGateway {
                 status: 'running',
                 active: this.spawnManager.size,
                 uptime: process.uptime(),
+                transport: this.transportHealthSnapshot(),
             }));
             return;
         }
@@ -1135,7 +1827,7 @@ export class InboundGateway {
             res.end(JSON.stringify({
                 ok: true,
                 active: handles.length,
-                claws: handles.map(h => ({
+                claws: handles.map((h) => ({
                     name: h.displayName,
                     agentName: h.agentName,
                     id: h.id,