ocuclaw 1.3.3 → 1.3.4

package/dist/gateway/openclaw-client.js

@@ -4,8 +4,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import WebSocket from "ws";
 import { createGatewayTimingLedger } from "./gateway-timing-ledger.js";
-
-// --- Constants ---
+import { sanitizeConnectReason } from "./sanitize-connect-reason.js";
 
 const DEVICE_KEY_FILE = "ocuclaw-device-key.json";
 const DEVICE_TOKEN_FILE = "ocuclaw-device-token.json";
@@ -24,11 +23,14 @@ const MIN_PROTOCOL_VERSION = 3;
 const MAX_PROTOCOL_VERSION = 4;
 const HISTORY_ACTIVITY_POLL_INTERVAL_MS = 500;
 const HISTORY_ACTIVITY_POLL_LIMIT = 40;
-// Per-request ACK timeout: fires only while waiting for the *initial* ack, not
-// during a mid-turn run. Comfortably above normal ack latency but below the
-// ~60s coarse tick-watch run backstop. Disarmed when an accepted ack arrives.
+
 const RPC_ACK_TIMEOUT_MS = 15000;
 
+const ESTABLISH_TIMEOUT_MS = 10000;
+
+const TICK_WATCH_MAX_INTERVAL_MS = 60000;
+const TICK_STALE_MULTIPLIER = 1.5;
+
 const THINKING_SUMMARY_KEYS = [
   "summary",
   "thinkingSummary",
@@ -110,12 +112,10 @@ function writeJsonFile(filePath, data) {
   try {
     fs.chmodSync(filePath, 0o600);
   } catch {
-    // best-effort
+
   }
 }
 
-// --- Base64url helpers ---
-
 function base64UrlEncode(buf) {
   return buf
     .toString("base64")
@@ -124,12 +124,6 @@ function base64UrlEncode(buf) {
     .replace(/=+$/g, "");
 }
 
-// --- Device identity ---
-
-/**
- * Extract raw 32-byte Ed25519 public key from SPKI DER.
- * Strips the standard 12-byte SPKI prefix for Ed25519 keys.
- */
 function derivePublicKeyRaw(publicKeyPem) {
   const key = crypto.createPublicKey(publicKeyPem);
   const spki = key.export({ type: "spki", format: "der" });
@@ -142,17 +136,11 @@ function derivePublicKeyRaw(publicKeyPem) {
   return spki;
 }
 
-/**
- * SHA-256 hex hash of the raw 32-byte public key.
- */
 function fingerprintPublicKey(publicKeyPem) {
   const raw = derivePublicKeyRaw(publicKeyPem);
   return crypto.createHash("sha256").update(raw).digest("hex");
 }
 
-/**
- * Generate a new Ed25519 keypair.
- */
 function generateIdentity() {
   const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
   const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
@@ -161,12 +149,9 @@ function generateIdentity() {
   return { deviceId, publicKeyPem, privateKeyPem };
 }
 
-/**
- * Load device identity from disk, or generate and persist a new one.
- */
 function loadOrCreateDeviceIdentity(persistencePaths, logger) {
   const deviceKeyPath = persistencePaths && persistencePaths.deviceKeyPath;
-  // Try loading existing key
+
   try {
     if (deviceKeyPath && fs.existsSync(deviceKeyPath)) {
       const raw = fs.readFileSync(deviceKeyPath, "utf8");
@@ -178,10 +163,10 @@ function loadOrCreateDeviceIdentity(persistencePaths, logger) {
         typeof parsed.publicKeyPem === "string" &&
         typeof parsed.privateKeyPem === "string"
       ) {
-        // Verify deviceId matches public key
+
         const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
         if (derivedId && derivedId !== parsed.deviceId) {
-          // Fix stored deviceId
+
           const updated = { ...parsed, deviceId: derivedId };
           writeJsonFile(deviceKeyPath, updated);
           logger.info(
@@ -204,10 +189,9 @@ function loadOrCreateDeviceIdentity(persistencePaths, logger) {
       }
     }
   } catch {
-    // Fall through to regenerate
+
   }
 
-  // Generate new identity
   const identity = generateIdentity();
   if (!deviceKeyPath) {
     logger.info(
@@ -229,12 +213,6 @@ function loadOrCreateDeviceIdentity(persistencePaths, logger) {
   return identity;
 }
 
-// --- Device token cache ---
-
-/**
- * Load cached device token from disk.
- * Returns token string or null.
- */
 function loadDeviceToken(deviceId, persistencePaths) {
   const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
   try {
@@ -255,9 +233,6 @@ function loadDeviceToken(deviceId, persistencePaths) {
   }
 }
 
-/**
- * Store device token to disk.
- */
 function storeDeviceToken(deviceId, token, role, scopes, persistencePaths) {
   const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
   if (!deviceTokenPath) return;
@@ -272,9 +247,6 @@ function storeDeviceToken(deviceId, token, role, scopes, persistencePaths) {
   writeJsonFile(deviceTokenPath, data);
 }
 
-/**
- * Clear cached device token.
- */
 function clearDeviceToken(persistencePaths) {
   const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
   try {
@@ -282,16 +254,10 @@ function clearDeviceToken(persistencePaths) {
       fs.unlinkSync(deviceTokenPath);
     }
   } catch {
-    // best-effort
+
   }
 }
 
-// --- Auth payload ---
-
-/**
- * Build the pipe-delimited device auth payload string.
- * Format: v2|{deviceId}|{clientId}|{clientMode}|{role}|{scopes}|{signedAtMs}|{token}|{nonce}
- */
 function buildDeviceAuthPayload(params) {
   const version = params.nonce ? "v2" : "v1";
   const scopes = params.scopes.join(",");
@@ -312,18 +278,12 @@ function buildDeviceAuthPayload(params) {
   return parts.join("|");
 }
 
-/**
- * Sign a payload string with Ed25519 private key, return base64url signature.
- */
 function signPayload(privateKeyPem, payload) {
   const key = crypto.createPrivateKey(privateKeyPem);
   const sig = crypto.sign(null, Buffer.from(payload, "utf8"), key);
   return base64UrlEncode(sig);
 }
 
-/**
- * Get the raw public key as base64url from PEM.
- */
 function publicKeyRawBase64Url(publicKeyPem) {
   return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
 }
@@ -389,7 +349,7 @@ function pickFirstStringEntry(obj, keys) {
 
 function normalizeThinkingText(raw) {
   if (typeof raw !== "string") return null;
-  // Match ActivityStatus iOS app behavior: strip bold markers and trim boundaries only.
+
   const cleaned = raw
     .replace(/\*\*/g, "")
     .trim();
@@ -618,10 +578,7 @@ function buildTerminalErrorActivity(data, fallbackRunId, fallbackSessionKey, fal
   if (label) activity.label = label;
   if (detail) activity.detail = detail;
   else if (label) activity.detail = label;
-  // failoverReason is set by the runtime when this terminal error is about to
-  // trigger a profile rotation or fallback retry. Surface it as a hint so the
-  // WebUI can suppress sticky failure feedback for runs that will retry on
-  // another auth profile or model rather than ending the user-visible turn.
+
   if (pickTrimmedString(source.failoverReason)) {
     activity.failoverPending = true;
   }
@@ -770,8 +727,6 @@ function hashThinkingKey(seed) {
   return crypto.createHash("sha1").update(seed).digest("hex").slice(0, 16);
 }
 
-// --- OpenClaw Gateway Client ---
-
 class OpenClawClient extends EventEmitter {
   constructor(opts = {}) {
     super();
@@ -786,50 +741,38 @@ class OpenClawClient extends EventEmitter {
     this._persistencePaths = resolvePersistencePaths(opts.stateDir);
     this._ws = null;
     this._stopped = false;
-    this._pending = new Map(); // id -> { resolve, reject, expectFinal }
+    this._pending = new Map();
     this._identity = null;
     this._connectNonce = null;
     this._connectSent = false;
     this._connectTimer = null;
-    // --- Socket-generation handshake gate (1008 reconnect-storm fix) ---
-    // Monotonic counter bumped on every _connect(); _handshakeGeneration is the
-    // watermark of the latest generation whose connect handshake has RESOLVED.
-    // A fresh socket is automatically "handshake-incomplete" (its generation is
-    // strictly greater than the watermark) with no extra reset bookkeeping —
-    // mirrors the existing _activeRunGeneration idiom. request() refuses any
-    // non-connect frame on a real ws socket whose generation has not yet
-    // handshaked, which is what enforces the gateway's "first frame must be
-    // connect" invariant across reconnect churn.
+
+    this._establishTimer = null;
+
     this._socketGeneration = 0;
     this._handshakeGeneration = -1;
     this._tickIntervalMs = 30000;
-    this._deviceToken = null; // cached from hello-ok
+    this._deviceToken = null;
 
-    // --- Reconnection (step 7) ---
     this._backoffMs = 1000;
     this._reconnectTimer = null;
 
-    // --- Tick watch (step 7) ---
     this._lastTick = null;
     this._tickWatchTimer = null;
 
-    // --- Agent run state (steps 4-5) ---
     this._activeRunId = null;
     this._activeRunSessionKey = null;
     this._activeRunStartedAtMs = null;
     this._activeRunGeneration = 0;
-    this._runTextBuffer = ""; // accumulated assistant text for current run
+    this._runTextBuffer = "";
 
-    // --- Agent identity (step 6) ---
     this._agentIdentity = null;
 
-    // --- Sequence tracking (step 8) ---
     this._lastSeq = null;
-    this._gapDuringRun = false; // set if gap detected while run active
+    this._gapDuringRun = false;
 
-    // --- History hydration (step 9) ---
     this._historyResolved = false;
-    this._eventQueue = []; // queued agent events until history resolves
+    this._eventQueue = [];
     this._historyActivityPollTimer = null;
     this._historyActivityPollInFlightGeneration = null;
     this._seenThinkingSummaryIds = new Set();
@@ -840,20 +783,15 @@ class OpenClawClient extends EventEmitter {
     this._timingLedger.setLogger(this._logger);
   }
 
-  /**
-   * Begin connecting to the gateway (non-blocking).
-   */
   start() {
     if (this._stopped) return;
 
-    // Load or create device identity (only on first start)
     if (!this._identity) {
       this._identity = loadOrCreateDeviceIdentity(
         this._persistencePaths,
         this._logger,
       );
 
-      // Load cached device token
       this._deviceToken = loadDeviceToken(
         this._identity.deviceId,
         this._persistencePaths,
@@ -866,15 +804,13 @@ class OpenClawClient extends EventEmitter {
     this._connect();
   }
 
-  /**
-   * Disconnect and stop.
-   */
   stop() {
     this._stopped = true;
     if (this._connectTimer) {
       clearTimeout(this._connectTimer);
       this._connectTimer = null;
     }
+    this._clearEstablishTimer();
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
@@ -890,31 +826,15 @@ class OpenClawClient extends EventEmitter {
     this.emit("status", "stopped");
   }
 
-  /**
-   * Send a request to the gateway. Returns a promise that resolves with the response payload.
-   * @param {string} method
-   * @param {object} [params]
-   * @param {{ expectFinal?: boolean }} [opts] - If expectFinal is true, skip intermediate
-   *   acks (status: "accepted") and resolve only on the final response.
-   */
   request(method, params, opts) {
-    // Capture the socket + generation at ENTRY so a reconnect that reassigns
-    // this._ws between entry and the synchronous send can never land this frame
-    // on a successor socket (kills the successor-socket race variant).
+
     const ws = this._ws;
     const gen = this._socketGeneration;
     if (!ws || ws !== this._ws || ws.readyState !== WebSocket.OPEN) {
-      // PRESERVE this exact literal — relay.test.js asserts it verbatim for the
-      // no-usable-socket case. The handshake gate below uses a DISTINCT message.
+
       return Promise.reject(new Error("gateway not connected"));
     }
-    // Per-socket handshake gate: a non-connect frame must not be the first frame
-    // on a freshly-OPEN-but-unregistered socket (gateway emits 1008). connect
-    // BYPASSES the gate (it IS the first allowed frame). The gate only applies
-    // to real `ws.WebSocket` sockets — the unit harnesses inject plain-object
-    // fakes ({ readyState: 1, send }) which are intentionally treated as
-    // already-handshaken so their request("agent"/"ping"/"chat.history") still
-    // sends with no harness changes.
+
     if (
       method !== "connect" &&
       ws instanceof WebSocket &&
@@ -932,9 +852,7 @@ class OpenClawClient extends EventEmitter {
     const promise = new Promise((resolve, reject) => {
       this._pending.set(id, { resolve, reject, expectFinal, method, diagnostic });
     });
-    // Per-request ACK timeout: reject if the initial ack never arrives. Disarmed
-    // when an accepted ack arrives (keepPending branch) so a legitimately
-    // long-running mid-turn run is NOT killed by this timeout.
+
     const timer = setTimeout(() => {
       const pendingEntry = this._pending.get(id);
       if (!pendingEntry) return;
@@ -964,15 +882,6 @@ class OpenClawClient extends EventEmitter {
     return promise;
   }
 
-  // --- Public: messaging (step 4) ---
-
-  /**
-   * Send a user message to the OpenClaw agent.
-   * Fire-and-forget: sends the request, streaming events arrive via event handlers.
-   * @param {string} text - Message text
-   * @param {string} [sessionKey="main"] - Session key
-   * @param {object|null} [attachment] - Optional image attachment payload
-   */
   sendMessage(text, sessionKey, attachment) {
     const key = sessionKey || "main";
     const idempotencyKey = crypto.randomUUID();
@@ -993,8 +902,6 @@ class OpenClawClient extends EventEmitter {
       ];
     }
 
-    // Resolve on the initial ack (accepted/queued) for immediate feedback.
-    // Agent streaming events arrive independently via event handlers.
     return this.request(
       "agent",
       params,
@@ -1012,13 +919,6 @@ class OpenClawClient extends EventEmitter {
     });
   }
 
-  // --- Public: agent identity (step 6) ---
-
-  /**
-   * Fetch agent identity from the gateway. Caches the result.
-   * @param {string} [sessionKey] - Optional session key
-   * @returns {Promise<{agentId, name, emoji, avatar}>}
-   */
   async fetchAgentIdentity(sessionKey) {
     const params = sessionKey ? { sessionKey } : {};
     const result = await this.request("agent.identity.get", params);
@@ -1028,12 +928,6 @@ class OpenClawClient extends EventEmitter {
     return result;
   }
 
-  /**
-   * Resolve an approval request.
-   * @param {string} id - Approval request ID
-   * @param {string} decision - "allow-once", "allow-always", or "deny"
-   * @returns {Promise}
-   */
   resolveApproval(id, decision) {
     const method =
       typeof id === "string" && id.startsWith("plugin:")
@@ -1076,28 +970,21 @@ class OpenClawClient extends EventEmitter {
     );
   }
 
-  // --- Internal: connection ---
-
   _connect() {
     if (this._stopped) return;
 
-    // Close any existing WebSocket to prevent parallel connections
-    // (e.g., from shutdown handler scheduling reconnect before close fires)
     if (this._ws) {
-      try { this._ws.close(); } catch { /* ignore */ }
+      try { this._ws.close(); } catch {  }
       this._ws = null;
     }
 
-    // Clear a stale 750ms connect-fallback timer left armed by a prior
-    // generation that opened then closed before it fired. _connect() resets
-    // _connectSent=false below, so a stale timer firing here would re-enter
-    // _sendConnect() on the NEW socket — harmless (still a connect frame, never
-    // a 1008), but it can produce a redundant connect. Clearing closes the edge.
     if (this._connectTimer) {
       clearTimeout(this._connectTimer);
       this._connectTimer = null;
     }
 
+    this._clearEstablishTimer();
+
     const url = this._gatewayUrl;
     this.emit("status", "connecting");
     this._logger.info(`[openclaw] Connecting to ${url}`);
@@ -1105,14 +992,8 @@ class OpenClawClient extends EventEmitter {
     this._connectNonce = null;
     this._connectSent = false;
 
-    // Bump the socket generation BEFORE constructing the new socket. The
-    // handshake watermark (_handshakeGeneration) intentionally STAYS at the
-    // prior value, so the about-to-be-created socket is automatically
-    // handshake-incomplete (its generation > watermark) until its own connect
-    // resolves. No watermark reset is needed.
     this._socketGeneration += 1;
 
-    // Reset per-connection state
     this._timingLedger.clear("connect_reset");
     this._lastSeq = null;
     this._lastTick = null;
@@ -1123,10 +1004,13 @@ class OpenClawClient extends EventEmitter {
     const ws = new WebSocket(url, { maxPayload: 25 * 1024 * 1024 });
     this._ws = ws;
 
+    this._armEstablishTimer(ws);
+
     ws.on("open", () => {
+
+      this._clearEstablishTimer();
       this._logger.info("[openclaw] WebSocket open, waiting for challenge...");
-      // Start a timeout: if we don't receive a challenge, send connect anyway
-      // (mirrors the reference client's queueConnect fallback)
+
       this._connectTimer = setTimeout(() => {
         this._sendConnect();
       }, 750);
@@ -1140,14 +1024,14 @@ class OpenClawClient extends EventEmitter {
       const reasonText = reason ? reason.toString() : "";
       this._logger.info(`[openclaw] WebSocket closed: ${code} ${reasonText}`);
       this._ws = null;
+      this._clearEstablishTimer();
       this._stopTickWatch();
       this._stopHistoryActivityPolling();
       this._timingLedger.clear("disconnect");
       this._flushPendingErrors(new Error(`gateway closed (${code}): ${reasonText}`));
       this.emit("disconnected", { code, reason: reasonText });
       this.emit("status", "disconnected");
-      // Only schedule reconnect if one isn't already pending
-      // (e.g., shutdown handler may have already scheduled with a specific delay)
+
       if (!this._reconnectTimer) {
         this._scheduleReconnect();
       }
@@ -1161,7 +1045,33 @@ class OpenClawClient extends EventEmitter {
     });
   }
 
-  // --- Internal: message handling ---
+  _armEstablishTimer(ws) {
+    const establishGeneration = this._socketGeneration;
+    this._establishTimer = setTimeout(() => {
+      this._establishTimer = null;
+      if (this._stopped || ws !== this._ws || establishGeneration !== this._socketGeneration) {
+        return;
+      }
+      this._logger.warn(
+        `[openclaw] Connect establishment timeout (${ESTABLISH_TIMEOUT_MS}ms), terminating socket`
+      );
+      try {
+        ws.terminate();
+      } catch {
+
+      }
+    }, ESTABLISH_TIMEOUT_MS);
+    if (this._establishTimer.unref) {
+      this._establishTimer.unref();
+    }
+  }
+
+  _clearEstablishTimer() {
+    if (this._establishTimer) {
+      clearTimeout(this._establishTimer);
+      this._establishTimer = null;
+    }
+  }
 
   _handleMessage(raw) {
     let parsed;
@@ -1172,21 +1082,17 @@ class OpenClawClient extends EventEmitter {
       return;
     }
 
-    // Emit protocol event for every incoming frame (step 10)
     this.emit("protocol", { direction: "in", frame: parsed });
 
-    // Event frames: { type: "event", event: "...", payload: ... }
     if (parsed.type === "event") {
       this._handleEvent(parsed);
       return;
     }
 
-    // Response frames: { type: "res", id: "...", ok: true/false, payload: ... }
     if (parsed.type === "res") {
       const pending = this._pending.get(parsed.id);
       if (!pending) return;
 
-      // If expectFinal, skip intermediate acks (status: "accepted") (step 4)
       const payload = parsed.payload;
       const status = payload && payload.status;
       const keepPending =
@@ -1200,21 +1106,19 @@ class OpenClawClient extends EventEmitter {
         keepPending,
       });
       if (keepPending) {
-        // The accepted ack arrived: the run is legitimately long-running, so
-        // disarm the ACK timeout (the coarse tick-watch remains the run backstop).
+
         if (pending.timer) {
           clearTimeout(pending.timer);
           pending.timer = null;
         }
-        // Track the runId from the ack
+
         if (payload.runId) {
           this._activeRunId = payload.runId;
           this._logger.info(`[openclaw] Agent run accepted: ${payload.runId}`);
         }
-        return; // Keep the pending entry, wait for final response
+        return;
       }
 
-      // Final settle: clear the ACK timeout before resolving/rejecting.
       if (pending.timer) {
         clearTimeout(pending.timer);
         pending.timer = null;
@@ -1232,7 +1136,7 @@ class OpenClawClient extends EventEmitter {
         if (parsed.error && parsed.error.data !== undefined) {
           err.data = parsed.error.data;
         }
-        // Check for retryable hint (step 7)
+
         if (parsed.error && parsed.error.retryable && parsed.error.retryAfterMs) {
           err.retryAfterMs = parsed.error.retryAfterMs;
         }
@@ -1242,10 +1146,8 @@ class OpenClawClient extends EventEmitter {
     }
   }
 
-  // --- Internal: event routing ---
-
   _handleEvent(evt) {
-    // connect.challenge is handled before sequence tracking
+
     if (evt.event === "connect.challenge") {
       const nonce =
         evt.payload && typeof evt.payload.nonce === "string" ? evt.payload.nonce : null;
@@ -1257,7 +1159,6 @@ class OpenClawClient extends EventEmitter {
       return;
     }
 
-    // --- Sequence tracking (step 8) ---
     const seq = typeof evt.seq === "number" ? evt.seq : null;
     if (seq !== null) {
       if (this._lastSeq !== null && seq > this._lastSeq + 1) {
@@ -1266,7 +1167,7 @@ class OpenClawClient extends EventEmitter {
           `[openclaw] Sequence gap: expected ${gapInfo.expected}, received ${gapInfo.received}`
         );
         this.emit("gap", gapInfo);
-        // Flag gap during active run for post-run re-fetch (step 8)
+
         if (this._activeRunId) {
           this._gapDuringRun = true;
         }
@@ -1274,29 +1175,25 @@ class OpenClawClient extends EventEmitter {
       this._lastSeq = seq;
     }
 
-    // --- Tick handling (step 7) ---
     if (evt.event === "tick") {
       this._lastTick = Date.now();
       return;
     }
 
-    // --- Shutdown handling (step 7) ---
     if (evt.event === "shutdown") {
       const payload = evt.payload || {};
       const restartMs = typeof payload.restartExpectedMs === "number" ? payload.restartExpectedMs : 5000;
       this._logger.info(`[openclaw] Gateway shutdown, reconnecting in ${restartMs}ms`);
       this.emit("status", "shutdown");
-      // Schedule reconnect after the expected restart delay
+
       this._scheduleReconnect(restartMs);
-      // Close the WS immediately to prevent the close handler from scheduling
-      // a second reconnect with normal backoff (double-reconnect race).
+
       if (this._ws) {
         this._ws.close(1000, "shutdown");
       }
       return;
     }
 
-    // --- Approval events ---
     if (evt.event === "exec.approval.requested") {
       this.emit("approval", evt.payload);
       return;
@@ -1317,7 +1214,6 @@ class OpenClawClient extends EventEmitter {
       return;
     }
 
-    // --- Agent events (step 5) ---
     if (evt.event === "agent") {
       const payload = evt.payload || {};
       const data = payload.data || {};
@@ -1330,25 +1226,10 @@ class OpenClawClient extends EventEmitter {
         phase: data.phase,
         data,
       });
-      // History-gate decouple (F18, history half): only the run-end COMMIT
-      // mutates the persistent message list downstream (lifecycle:end ->
-      // emit("message") -> conversationState.addMessage, a blind push), and the
-      // history hydrate is a DESTRUCTIVE replace-all (conversation-state.ts
-      // hydrate()). To avoid the commit being clobbered/duplicated by a later
-      // hydrate, the commit must still run AFTER history resolves. Every other
-      // agent event (lifecycle:start, assistant/streaming, tool, error) emits
-      // only transient/live effects (activity/streaming/error) that hydrate
-      // never touches, so processing them immediately is safe and removes the
-      // reconnect responsiveness delay. The intact commit event is queued and
-      // replayed via _drainEventQueue, preserving the de-dup contract exactly.
+
       const isCommitEvent = data.phase === "end" && payload.stream === "lifecycle";
       if (isCommitEvent && !this._historyResolved) {
-        // Snapshot the commit-relevant LIVE instance state at enqueue time. The
-        // lifecycle:end branch reads _runTextBuffer / _activeRunId / _gapDuringRun
-        // (and _activeRunSessionKey as the session-key fallback) — all of which a
-        // LATER run's lifecycle:start (_beginActiveRun) or an _invalidateActiveRun
-        // mutates before the queue drains. Capturing now keeps the deferred commit
-        // contemporaneous with its own run, restoring pre-F18 replay semantics.
+
         this._eventQueue.push({
           payload: evt.payload,
           capturedCommit: {
@@ -1365,12 +1246,6 @@ class OpenClawClient extends EventEmitter {
     }
   }
 
-  // --- Internal: agent streaming (step 5) ---
-
-  /**
-   * Handle an agent event payload.
-   * Buffers assistant text deltas, emits activity/message events.
-   */
   _handleAgentEvent(payload, capturedCommit) {
     if (!payload) return;
 
@@ -1430,19 +1305,14 @@ class OpenClawClient extends EventEmitter {
         break;
 
       case "end": {
-        // Prefer the snapshot captured at history-gate enqueue time (F18 commit
-        // defer). When the end event is processed IMMEDIATELY (history already
-        // resolved), capturedCommit is undefined and live instance state is read
-        // exactly as before — byte-for-byte unchanged. When DEFERRED, a later
-        // run's start (or an invalidate) may have already clobbered these shared
-        // fields, so the snapshot keeps the commit contemporaneous with its run.
+
         const committedActiveRunId = capturedCommit
           ? capturedCommit.activeRunId
           : this._activeRunId;
         const committedActiveRunSessionKey = capturedCommit
           ? capturedCommit.activeRunSessionKey
           : this._activeRunSessionKey;
-        // Assemble full response from buffered text
+
         const fullText = capturedCommit ? capturedCommit.fullText : this._runTextBuffer;
         const completedRunId = normalizeRunId(committedActiveRunId) || normalizeRunId(runId);
         const completedSessionKey =
@@ -1451,22 +1321,10 @@ class OpenClawClient extends EventEmitter {
           null;
         const gapDuringRun = capturedCommit ? capturedCommit.gapDuringRun : this._gapDuringRun;
 
-        // Invalidate run state before emitting terminal idle so late history polls
-        // cannot reopen thinking for a completed run.
         this._timingLedger.recordRunTerminal({
           runId: completedRunId,
         });
-        // Reconnect-window guard (F18 successor-run protection): a DEFERRED
-        // commit (capturedCommit present) drains AFTER its run ended, and a
-        // LATER run's lifecycle:start may already have become the live active
-        // run (set _activeRunId, armed history polling, started buffering its
-        // own text) before drain. An unconditional invalidate here would tear
-        // down that live successor — stop its thinking-summary polling, null
-        // its _activeRunId, and clear its _runTextBuffer — wiping state that
-        // belongs to a run that has NOT ended. Only invalidate when this commit
-        // IS the live active run (its own run, or a non-deferred/live commit
-        // where the snapshot is absent). When _activeRunId is already null there
-        // is nothing live to protect, so skipping the invalidate is a no-op.
+
         const commitIsLiveActiveRun =
           normalizeRunId(this._activeRunId) === normalizeRunId(committedActiveRunId);
         if (!capturedCommit || commitIsLiveActiveRun) {
@@ -1490,7 +1348,6 @@ class OpenClawClient extends EventEmitter {
           `[openclaw] Agent run ended: ${completedRunId} (${fullText.length} chars)`
         );
 
-        // If there was a gap during this run, re-fetch history (step 8)
         if (gapDuringRun) {
           this._logger.info("[openclaw] Gap detected during run, re-fetching history");
           this._fetchHistory(completedSessionKey || "main").catch((err) => {
@@ -1542,7 +1399,6 @@ class OpenClawClient extends EventEmitter {
       "assistant_event",
     );
 
-    // Gateway sends accumulated text (full text so far), not deltas
     if (typeof data.text === "string") {
       const previousTextLength = this._runTextBuffer.length;
       const gatewayReceivedAtMs = Date.now();
@@ -1602,10 +1458,7 @@ class OpenClawClient extends EventEmitter {
 
     const poll = () => {
       this._pollHistoryActivity().catch((err) => {
-        // Suppress benign transient rejections during reconnect churn: the
-        // no-socket "gateway not connected" case AND the new handshake-gate
-        // reject (handshake_pending / "gateway handshake in flight"), so the
-        // 1008 fix does not emit spurious poll-failed warnings in its own window.
+
         const benignTransient =
           !!err &&
           (err.code === "handshake_pending" ||
@@ -1621,8 +1474,6 @@ class OpenClawClient extends EventEmitter {
       });
     };
 
-    // Let setInterval fire the first poll one interval out so the initial
-    // chat.history fetch doesn't contend with the first streaming chunk landing.
     this._historyActivityPollTimer = setInterval(
       poll,
       HISTORY_ACTIVITY_POLL_INTERVAL_MS,
@@ -1771,8 +1622,6 @@ class OpenClawClient extends EventEmitter {
     });
   }
 
-  // --- Internal: handshake ---
-
   _sendConnect() {
     if (this._connectSent) return;
     this._connectSent = true;
@@ -1788,14 +1637,12 @@ class OpenClawClient extends EventEmitter {
       return;
     }
 
-    // Choose auth token: prefer cached device token, fall back to gateway token
     const authToken = this._deviceToken || this._gatewayToken || undefined;
     const canFallback = Boolean(this._deviceToken && this._gatewayToken);
 
     const signedAtMs = Date.now();
     const nonce = this._connectNonce || undefined;
 
-    // Build device auth payload
     const payload = buildDeviceAuthPayload({
       deviceId: identity.deviceId,
       clientId: CLIENT_ID,
@@ -1807,10 +1654,8 @@ class OpenClawClient extends EventEmitter {
       nonce,
     });
 
-    // Sign with Ed25519 private key
     const signature = signPayload(identity.privateKeyPem, payload);
 
-    // Build connect request params
     const params = {
       minProtocol: MIN_PROTOCOL_VERSION,
       maxProtocol: MAX_PROTOCOL_VERSION,
@@ -1835,10 +1680,6 @@ class OpenClawClient extends EventEmitter {
 
     this._logger.info("[openclaw] Sending connect request...");
 
-    // Capture the generation this connect is being sent for. The resolve below
-    // must only mark THIS generation handshaken — if a disconnect+reconnect
-    // bumped _socketGeneration before the connect resolved, this resolve is
-    // stale and must NOT open the gate for the new in-flight socket.
     const connectGeneration = this._socketGeneration;
 
     this.request("connect", params)
@@ -1848,19 +1689,13 @@ class OpenClawClient extends EventEmitter {
             `tick=${helloOk.policy && helloOk.policy.tickIntervalMs}ms`
         );
 
-        // Reset backoff on successful connect (step 7)
         this._backoffMs = 1000;
 
-        // Cache tick interval
-        if (helloOk.policy && typeof helloOk.policy.tickIntervalMs === "number") {
-          this._tickIntervalMs = helloOk.policy.tickIntervalMs;
-        }
+        this._applyConnectPolicy(helloOk.policy);
 
-        // Start tick watch (step 7)
         this._lastTick = Date.now();
         this._startTickWatch();
 
-        // Cache device token if provided
         if (helloOk.auth && helloOk.auth.deviceToken) {
           this._deviceToken = helloOk.auth.deviceToken;
           storeDeviceToken(
@@ -1873,12 +1708,6 @@ class OpenClawClient extends EventEmitter {
           this._logger.info("[openclaw] Device token cached");
         }
 
-        // Open the handshake gate for THIS socket's generation BEFORE emitting
-        // "connected" (so refreshUpstreamBootstrap, fired on the connected event,
-        // sees an open gate). Guard against a stale resolve: if a reconnect
-        // already superseded this socket, _socketGeneration has advanced past
-        // connectGeneration and we must NOT mark the new in-flight socket
-        // handshaken — that would re-admit the very 1008 race this fix closes.
         if (connectGeneration === this._socketGeneration) {
           this._handshakeGeneration = connectGeneration;
         }
@@ -1889,7 +1718,6 @@ class OpenClawClient extends EventEmitter {
         });
         this.emit("status", "connected");
 
-        // Post-connect: fetch agent identity (step 6) and chat history (step 9)
         this._postConnect().catch((err) => {
           this._logger.error(`[openclaw] Post-connect setup failed: ${err.message}`);
           this.emit("error", err);
@@ -1898,7 +1726,6 @@ class OpenClawClient extends EventEmitter {
       .catch((err) => {
         this._logger.error(`[openclaw] Connect failed: ${err.message}`);
 
-        // If we were using a cached device token and have a fallback, clear and retry
         if (canFallback) {
           this._logger.info(
             "[openclaw] Clearing cached device token, will use gateway token on next connect"
@@ -1907,6 +1734,11 @@ class OpenClawClient extends EventEmitter {
           clearDeviceToken(this._persistencePaths);
         }
 
+        this.emit("connectFailed", {
+          reason: sanitizeConnectReason(err && err.message),
+          minProtocol: MIN_PROTOCOL_VERSION,
+          maxProtocol: MAX_PROTOCOL_VERSION,
+        });
         this.emit("error", err);
         if (this._ws) {
           this._ws.close(1008, "connect failed");
@@ -1914,32 +1746,22 @@ class OpenClawClient extends EventEmitter {
       });
   }
 
-  // --- Internal: post-connect setup (steps 6, 9) ---
-
   async _postConnect() {
-    // Fetch agent identity (step 6) — non-blocking, don't gate on this
+
     this.fetchAgentIdentity().catch((err) => {
       this._logger.error(`[openclaw] Agent identity fetch failed: ${err.message}`);
     });
 
-    // Fetch chat history (step 9) — blocks agent event processing until done
     try {
       await this._fetchHistory("main");
     } catch (err) {
       this._logger.error(`[openclaw] Chat history fetch failed: ${err.message}`);
     }
 
-    // Mark history as resolved and drain queued events
     this._historyResolved = true;
     this._drainEventQueue();
   }
 
-  // --- Internal: chat history (step 9) ---
-
-  /**
-   * Fetch chat history from the gateway.
-   * @param {string} sessionKey
-   */
   async _fetchHistory(sessionKey) {
     const result = await this.request("chat.history", {
       sessionKey,
@@ -1957,9 +1779,6 @@ class OpenClawClient extends EventEmitter {
     return result;
   }
 
-  /**
-   * Drain queued agent events that arrived before history resolved.
-   */
   _drainEventQueue() {
     const queue = this._eventQueue;
     this._eventQueue = [];
@@ -1968,28 +1787,15 @@ class OpenClawClient extends EventEmitter {
     }
   }
 
-  // --- Internal: reconnection (step 7) ---
-
-  /**
-   * Schedule a reconnect attempt with exponential backoff.
-   * @param {number} [delayOverride] - Override the backoff delay (e.g., for shutdown events)
-   */
   _scheduleReconnect(delayOverride) {
     if (this._stopped) return;
 
-    // Capture the current base before advancing so jitter is computed from the
-    // same epoch value that would previously have been used as the raw delay.
     const base = this._backoffMs;
 
-    // Advance backoff for next time (unless overridden)
     if (typeof delayOverride !== "number") {
       this._backoffMs = Math.min(this._backoffMs * 2, 30000);
     }
 
-    // Apply equal jitter to the scheduled delay so concurrent reconnect storms
-    // don't all fire at the same instant. The stored _backoffMs base is NOT
-    // mutated — doubling/cap/reset invariants are preserved.
-    // delayOverride bypasses jitter (used for e.g. shutdown-driven reconnects).
     const delay =
       typeof delayOverride === "number"
         ? delayOverride
@@ -2006,26 +1812,26 @@ class OpenClawClient extends EventEmitter {
       this._reconnectTimer = null;
       this.start();
     }, delay);
-    // Don't prevent process exit while waiting to reconnect
+
     if (this._reconnectTimer.unref) {
       this._reconnectTimer.unref();
     }
   }
 
-  // --- Internal: tick watch (step 7) ---
+  _applyConnectPolicy(policy) {
+    if (policy && typeof policy.tickIntervalMs === "number") {
+      this._tickIntervalMs = Math.min(policy.tickIntervalMs, TICK_WATCH_MAX_INTERVAL_MS);
+    }
+  }
 
-  /**
-   * Start watching for stale connections via tick timeout.
-   * If no tick received within 2x tickIntervalMs, close and reconnect.
-   */
   _startTickWatch() {
     this._stopTickWatch();
-    const interval = Math.max(this._tickIntervalMs, 1000);
+    const pollMs = Math.max(Math.floor(this._tickIntervalMs / 4), 1000);
     this._tickWatchTimer = setInterval(() => {
       if (this._stopped) return;
       if (!this._lastTick) return;
       const elapsed = Date.now() - this._lastTick;
-      if (elapsed > this._tickIntervalMs * 2) {
+      if (elapsed > this._tickIntervalMs * TICK_STALE_MULTIPLIER) {
         this._logger.warn(
           `[openclaw] Tick timeout (${elapsed}ms since last tick), closing connection`
         );
@@ -2033,16 +1839,13 @@ class OpenClawClient extends EventEmitter {
           this._ws.close(4000, "tick timeout");
         }
       }
-    }, interval);
-    // Don't prevent process exit
+    }, pollMs);
+
     if (this._tickWatchTimer.unref) {
       this._tickWatchTimer.unref();
     }
   }
 
-  /**
-   * Stop the tick watch timer.
-   */
   _stopTickWatch() {
     if (this._tickWatchTimer) {
       clearInterval(this._tickWatchTimer);
@@ -2050,12 +1853,9 @@ class OpenClawClient extends EventEmitter {
     }
   }
 
-  // --- Internal: helpers ---
-
   _flushPendingErrors(err) {
     for (const [, pending] of this._pending) {
-      // Clear the per-request ACK timeout so a flushed entry cannot fire a
-      // late reject after the map is cleared.
+
       if (pending.timer) {
         clearTimeout(pending.timer);
         pending.timer = null;