oomi-ai 0.2.4 → 0.2.6

package/README.md

@@ -72,6 +72,7 @@ Agent-intent mapping (recommended):
 Important distinction:
 - `pairCode` is one-time and used internally by the pair/bootstrap flow.
 - Invite auth links are the required user flow.
+- Managed chat connect now uses OpenClaw challenge auth (`connect.challenge` nonce + signed device payload) in the local bridge path.
 
 Sync personas from the repo into the backend registry:
 ```
@@ -109,6 +110,8 @@ Restart OpenClaw after running `oomi init` or `oomi openclaw install`.
   - `OOMI_SKIP_UPDATE_CHECK=1` disables checks
   - `OOMI_UPDATE_CHECK_INTERVAL_MS=<ms>` changes check interval
   - `OOMI_UPDATE_CHECK_TIMEOUT_MS=<ms>` changes network timeout
+  - `OOMI_BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS=<ms>` changes local gateway socket connect timeout
+  - `OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS=<ms>` changes wait timeout for gateway `connect.challenge` nonce
 
 ## Package Audit + Publish (pnpm)
 ```

package/bin/oomi-ai.js

@@ -3,7 +3,9 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { spawn } from 'child_process';
-import { randomUUID } from 'crypto';
+import { createPrivateKey, createPublicKey, randomUUID, sign as cryptoSign } from 'crypto';
+import net from 'net';
+import { lookup as dnsLookup } from 'dns/promises';
 import WebSocket from 'ws';
 import { ensureSessionBridge, forwardFrameToSession, flushSessionQueue } from './sessionBridgeState.js';
 
@@ -14,6 +16,18 @@ const PACKAGE_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname
 const UPDATE_STATE_FILE = path.join(os.homedir(), '.openclaw', 'oomi-ai-update-check.json');
 const DEFAULT_UPDATE_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1200;
+const BRIDGE_RECONNECT_BASE_MS = 2000;
+const BRIDGE_RECONNECT_MAX_MS = 60000;
+const BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS = parsePositiveInteger(
+  process.env.OOMI_BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS,
+  10000
+);
+const BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS = parsePositiveInteger(
+  process.env.OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS,
+  3000
+);
+const DEVICE_IDENTITY_PATH = path.join(os.homedir(), '.openclaw', 'identity', 'device.json');
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
 
 function parsePositiveInteger(value, fallback) {
   const num = Number(value);
@@ -149,6 +163,9 @@ Commands:
   openclaw plugin
     Print OpenClaw extension install/config guidance for Oomi channel plugin.
 
+  openclaw status
+    Show bridge state + runtime health from local status files.
+
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
@@ -162,7 +179,7 @@ Common flags:
   --broker-http URL      Managed broker HTTPS URL (for pair claim)
   --broker-ws URL        Managed broker device WS URL (wss://.../cable)
   --pair-code CODE       One-time pairing code from Oomi
-  --app-url URL          Oomi app URL used for pairing APIs (default: http://127.0.0.1:3456)
+  --app-url URL          Oomi app URL used for pairing APIs; bridge can also refresh managed broker URLs from it
   --label TEXT           Pairing label shown in broker logs
   --session-key KEY      Session key used in generated connect URL
   --detach               Start bridge in background and exit
@@ -537,6 +554,10 @@ function resolveBridgeStatePath() {
   return path.join(os.homedir(), '.openclaw', 'oomi-bridge.json');
 }
 
+function resolveBridgeStatusPath() {
+  return path.join(os.homedir(), '.openclaw', 'oomi-bridge-status.json');
+}
+
 function defaultDeviceId() {
   const host = os.hostname().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'openclaw';
   return `oomi-${host}-${randomUUID().slice(0, 8)}`;
@@ -566,6 +587,27 @@ function writeBridgeState(nextState) {
   writeFile(statePath, JSON.stringify(nextState, null, 2) + '\n');
 }
 
+function readBridgeStatus() {
+  return readJsonSafe(resolveBridgeStatusPath()) || {};
+}
+
+function writeBridgeStatus(nextStatus) {
+  const statusPath = resolveBridgeStatusPath();
+  ensureDir(path.dirname(statusPath));
+  writeFile(statusPath, JSON.stringify(nextStatus, null, 2) + '\n');
+}
+
+function updateBridgeStatus(partial) {
+  const current = readBridgeStatus();
+  const next = {
+    ...current,
+    ...partial,
+    updatedAt: new Date().toISOString(),
+  };
+  writeBridgeStatus(next);
+  return next;
+}
+
 async function claimBridgeDeviceToken({ brokerHttp, pairCode, deviceId }) {
   const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/claim`, {
     method: 'POST',
@@ -634,13 +676,109 @@ async function fetchManagedGatewayConfig({ appUrl }) {
   return payload;
 }
 
-function injectGatewayAuth(frameText, gatewayAuth) {
+function base64UrlEncode(value) {
+  return Buffer.from(value)
+    .toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/g, '');
+}
+
+function normalizeDeviceMetadataForAuth(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32));
+}
+
+function publicKeyRawBase64UrlFromPem(publicKeyPem) {
+  const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  const raw =
+    der.length === ED25519_SPKI_PREFIX.length + 32 &&
+    der.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)
+      ? der.subarray(ED25519_SPKI_PREFIX.length)
+      : der;
+  return base64UrlEncode(raw);
+}
+
+function signDevicePayload(privateKeyPem, payload) {
+  const key = createPrivateKey(privateKeyPem);
+  return base64UrlEncode(cryptoSign(null, Buffer.from(payload, 'utf8'), key));
+}
+
+function buildDeviceAuthPayloadV3({
+  deviceId,
+  clientId,
+  clientMode,
+  role,
+  scopes,
+  signedAtMs,
+  token,
+  nonce,
+  platform,
+  deviceFamily,
+}) {
+  return [
+    'v3',
+    deviceId,
+    clientId,
+    clientMode,
+    role,
+    scopes.join(','),
+    String(signedAtMs),
+    token || '',
+    nonce,
+    normalizeDeviceMetadataForAuth(platform),
+    normalizeDeviceMetadataForAuth(deviceFamily),
+  ].join('|');
+}
+
+function loadGatewayDeviceIdentity() {
+  if (!fs.existsSync(DEVICE_IDENTITY_PATH)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFile(DEVICE_IDENTITY_PATH));
+    if (
+      parsed &&
+      parsed.version === 1 &&
+      typeof parsed.deviceId === 'string' &&
+      typeof parsed.publicKeyPem === 'string' &&
+      typeof parsed.privateKeyPem === 'string'
+    ) {
+      return {
+        deviceId: parsed.deviceId.trim(),
+        publicKeyPem: parsed.publicKeyPem,
+        privateKeyPem: parsed.privateKeyPem,
+      };
+    }
+  } catch {
+    // no-op
+  }
+  return null;
+}
+
+function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}) {
+  const connectNonce = typeof options.connectNonce === 'string' ? options.connectNonce.trim() : '';
+  const deviceIdentity = options.deviceIdentity || null;
+
   try {
     const frame = JSON.parse(frameText);
     if (frame?.type !== 'req' || frame?.method !== 'connect') {
-      return frameText;
+      return { frameText, waitForChallenge: false };
     }
+
     const params = frame.params && typeof frame.params === 'object' ? frame.params : {};
+
+    const client = params.client && typeof params.client === 'object' ? params.client : {};
+    client.id = typeof client.id === 'string' && client.id.trim() ? client.id.trim() : 'webchat-ui';
+    client.version = typeof client.version === 'string' && client.version.trim() ? client.version.trim() : '0.1.0';
+    client.platform = typeof client.platform === 'string' && client.platform.trim() ? client.platform.trim() : process.platform;
+    client.mode = typeof client.mode === 'string' && client.mode.trim() ? client.mode.trim() : 'webchat';
+    params.client = client;
+
+    params.role = typeof params.role === 'string' && params.role.trim() ? params.role.trim() : 'operator';
+
     const existingScopes = Array.isArray(params.scopes)
       ? params.scopes.filter((value) => typeof value === 'string' && value.trim())
       : [];
@@ -652,17 +790,63 @@ function injectGatewayAuth(frameText, gatewayAuth) {
     }
     params.scopes = existingScopes;
 
+    if (!Array.isArray(params.caps)) {
+      params.caps = [];
+    }
+    if (!Array.isArray(params.commands)) {
+      params.commands = [];
+    }
+    if (!params.permissions || typeof params.permissions !== 'object') {
+      params.permissions = {};
+    }
+
     const auth = {};
-    if (gatewayAuth.token) auth.token = gatewayAuth.token;
-    else if (gatewayAuth.password) auth.password = gatewayAuth.password;
+    if (gatewayAuth.token) {
+      auth.token = gatewayAuth.token;
+    } else if (gatewayAuth.password) {
+      auth.password = gatewayAuth.password;
+    }
     if (Object.keys(auth).length > 0) {
       params.auth = auth;
-      frame.params = params;
-      return JSON.stringify(frame);
     }
-    return frameText;
+
+    if (deviceIdentity) {
+      if (!connectNonce) {
+        return { frameText: null, waitForChallenge: true };
+      }
+
+      const signedAtMs = Date.now();
+      const tokenForSignature =
+        typeof auth.token === 'string' && auth.token.trim()
+          ? auth.token.trim()
+          : (typeof auth.deviceToken === 'string' && auth.deviceToken.trim() ? auth.deviceToken.trim() : '');
+
+      const payload = buildDeviceAuthPayloadV3({
+        deviceId: deviceIdentity.deviceId,
+        clientId: client.id,
+        clientMode: client.mode,
+        role: params.role,
+        scopes: existingScopes,
+        signedAtMs,
+        token: tokenForSignature,
+        nonce: connectNonce,
+        platform: client.platform,
+        deviceFamily: typeof client.deviceFamily === 'string' ? client.deviceFamily : '',
+      });
+      const signature = signDevicePayload(deviceIdentity.privateKeyPem, payload);
+      params.device = {
+        id: deviceIdentity.deviceId,
+        publicKey: publicKeyRawBase64UrlFromPem(deviceIdentity.publicKeyPem),
+        signature,
+        signedAt: signedAtMs,
+        nonce: connectNonce,
+      };
+    }
+
+    frame.params = params;
+    return { frameText: JSON.stringify(frame), waitForChallenge: false };
   } catch {
-    return frameText;
+    return { frameText, waitForChallenge: false };
   }
 }
 
@@ -674,29 +858,219 @@ function parseJsonPayload(raw) {
   }
 }
 
+function bridgeNowIso() {
+  return new Date().toISOString();
+}
+
+function extractErrorCode(err) {
+  if (!err || typeof err !== 'object') return '';
+  const value = err.code;
+  return typeof value === 'string' ? value.trim().toUpperCase() : '';
+}
+
+function extractErrorMessage(err) {
+  if (!err) return '';
+  if (typeof err === 'string') return err.trim();
+  if (err instanceof Error) return err.message.trim();
+  return String(err).trim();
+}
+
+function classifyBridgeFailure({ err, reason = '', code = '', forceClass = '' } = {}) {
+  const errorCode = (code || extractErrorCode(err)).toUpperCase();
+  const message = [extractErrorMessage(err), String(reason || '').trim()].filter(Boolean).join(' | ');
+  const text = `${errorCode} ${message}`.toLowerCase();
+
+  let failureClass = forceClass || 'unknown';
+  let retryable = true;
+  let hint = 'Check broker URL, network path, and bridge token.';
+  let baseDelayMs = BRIDGE_RECONNECT_BASE_MS;
+
+  if (
+    errorCode === 'ENOTFOUND' ||
+    errorCode === 'EAI_AGAIN' ||
+    text.includes('enotfound') ||
+    text.includes('name resolution') ||
+    text.includes('dns')
+  ) {
+    failureClass = 'dns_resolution';
+    hint = 'Host resolution failed. Verify DNS/network access to the broker host.';
+    baseDelayMs = 5000;
+  } else if (
+    text.includes('unauthorized') ||
+    text.includes('forbidden') ||
+    text.includes('invalid token') ||
+    text.includes('token expired') ||
+    text.includes('broker rejected')
+  ) {
+    failureClass = 'auth_rejected';
+    retryable = false;
+    hint = 'Bridge token is invalid/expired. Re-run: oomi openclaw pair --app-url <url>.';
+    baseDelayMs = BRIDGE_RECONNECT_MAX_MS;
+  } else if (
+    errorCode === 'ECONNREFUSED' ||
+    errorCode === 'ENETUNREACH' ||
+    errorCode === 'EHOSTUNREACH' ||
+    errorCode === 'ETIMEDOUT' ||
+    text.includes('socket hang up') ||
+    text.includes('abnormal closure')
+  ) {
+    failureClass = 'network';
+    hint = 'Broker network path is unavailable. Check connectivity/firewall/proxy settings.';
+    baseDelayMs = 3000;
+  }
+
+  return {
+    errorCode: errorCode || 'UNKNOWN',
+    message: message || 'unknown bridge error',
+    failureClass,
+    retryable,
+    hint,
+    baseDelayMs,
+  };
+}
+
+function computeReconnectDelayMs(attempt, baseDelayMs) {
+  const growth = Math.min(BRIDGE_RECONNECT_MAX_MS, Math.round(baseDelayMs * (2 ** Math.max(0, attempt - 1))));
+  const jitter = Math.floor(growth * (Math.random() * 0.25));
+  return Math.min(BRIDGE_RECONNECT_MAX_MS, growth + jitter);
+}
+
+async function assertTcpReachable(urlValue, timeoutMs = 1500) {
+  const url = new URL(urlValue);
+  const host = url.hostname || '127.0.0.1';
+  const port = Number(url.port || (url.protocol === 'wss:' || url.protocol === 'https:' ? 443 : 80));
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error(`Invalid port in URL: ${urlValue}`);
+  }
+
+  await new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port });
+    let finished = false;
+    const done = (fn) => (value) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      socket.destroy();
+      fn(value);
+    };
+    const timer = setTimeout(done(reject), timeoutMs, new Error(`TCP connect timeout (${host}:${port})`));
+    socket.once('connect', done(resolve));
+    socket.once('error', done(reject));
+  });
+}
+
+async function runBridgePreflight({ brokerWs, gatewayUrl, gatewayConfigPath }) {
+  let brokerUrl;
+  try {
+    brokerUrl = new URL(brokerWs);
+  } catch {
+    throw new Error(`Invalid broker WS URL: ${brokerWs}`);
+  }
+  if (brokerUrl.protocol !== 'ws:' && brokerUrl.protocol !== 'wss:') {
+    throw new Error(`Broker WS URL must use ws:// or wss:// (received ${brokerUrl.protocol})`);
+  }
+
+  const brokerHost = brokerUrl.hostname;
+  if (!brokerHost) {
+    throw new Error('Broker WS URL is missing hostname.');
+  }
+  await dnsLookup(brokerHost);
+
+  let parsedGatewayUrl;
+  try {
+    parsedGatewayUrl = new URL(gatewayUrl);
+  } catch {
+    throw new Error(`Invalid local gateway URL (${gatewayUrl}) from ${gatewayConfigPath}`);
+  }
+  if (parsedGatewayUrl.protocol !== 'ws:') {
+    throw new Error(`Local gateway URL must use ws:// (received ${parsedGatewayUrl.protocol})`);
+  }
+  await assertTcpReachable(parsedGatewayUrl.toString());
+}
+
+function buildBridgeDetachArgs(rawFlags = {}) {
+  const orderedKeys = [
+    'broker-http',
+    'broker-ws',
+    'pair-code',
+    'app-url',
+    'device-id',
+    'device-token',
+  ];
+  const args = [process.argv[1], 'openclaw', 'bridge'];
+
+  for (const key of orderedKeys) {
+    const value = rawFlags[key];
+    if (value === undefined || value === null || value === false) continue;
+    if (value === true) {
+      args.push(`--${key}`);
+      continue;
+    }
+    const text = String(value).trim();
+    if (!text) continue;
+    args.push(`--${key}`, text);
+  }
+
+  return args;
+}
+
+function startBridgeDetachedProcess(rawFlags = {}) {
+  const args = buildBridgeDetachArgs(rawFlags);
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return child.pid;
+}
+
+async function resolveBridgeRuntimeConfig(flags, bridgeState) {
+  const explicitBrokerHttp = String(flags['broker-http'] || '').trim();
+  const explicitBrokerWs = String(flags['broker-ws'] || '').trim();
+  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || '').trim();
+
+  let brokerHttp = String(explicitBrokerHttp || process.env.OOMI_CHAT_BROKER_HTTP_URL || bridgeState.brokerHttp || '').trim();
+  let brokerWs = String(explicitBrokerWs || process.env.OOMI_CHAT_BROKER_DEVICE_WS_URL || bridgeState.brokerWs || '').trim();
+  let managedConfigUsed = false;
+  let managedConfigError = '';
+
+  if (appUrl && (!explicitBrokerHttp || !explicitBrokerWs)) {
+    try {
+      const managedConfig = await fetchManagedGatewayConfig({ appUrl });
+      managedConfigUsed = true;
+      if (!explicitBrokerHttp) {
+        brokerHttp = String(managedConfig.brokerHttpUrl || '').trim();
+      }
+      if (!explicitBrokerWs) {
+        brokerWs = String(managedConfig.brokerDeviceWsUrl || '').trim();
+      }
+    } catch (err) {
+      managedConfigError = extractErrorMessage(err);
+      if (!brokerWs) {
+        throw err;
+      }
+    }
+  }
+
+  return {
+    appUrl,
+    brokerHttp,
+    brokerWs,
+    managedConfigUsed,
+    managedConfigError,
+  };
+}
+
 async function startOpenclawBridge(flags) {
   const bridgeState = readBridgeState();
-  const brokerHttp = String(
-    flags['broker-http'] ||
-      process.env.OOMI_CHAT_BROKER_HTTP_URL ||
-      bridgeState.brokerHttp ||
-      ''
-  ).trim();
-  const brokerWs = String(
-    flags['broker-ws'] ||
-      process.env.OOMI_CHAT_BROKER_DEVICE_WS_URL ||
-      bridgeState.brokerWs ||
-      ''
-  ).trim();
+  const runtimeConfig = await resolveBridgeRuntimeConfig(flags, bridgeState);
+  const brokerHttp = runtimeConfig.brokerHttp;
+  const brokerWs = runtimeConfig.brokerWs;
   const deviceId = resolveDeviceId(flags, bridgeState);
   const pairCode = String(flags['pair-code'] || '').trim().toUpperCase();
   const explicitDeviceToken = String(flags['device-token'] || '').trim();
-  const canReuseStateToken =
-    String(bridgeState.deviceId || '').trim() === deviceId &&
-    String(bridgeState.brokerWs || '').trim() === brokerWs &&
-    String(bridgeState.brokerHttp || '').trim() === brokerHttp;
   let deviceToken = explicitDeviceToken;
-  if (!deviceToken && canReuseStateToken) {
+  if (!deviceToken && String(bridgeState.deviceId || '').trim() === deviceId) {
     deviceToken = String(bridgeState.deviceToken || '').trim();
   }
 
@@ -730,12 +1104,71 @@ async function startOpenclawBridge(flags) {
   if (!gateway.token && !gateway.password) {
     throw new Error(`Gateway auth token/password not found in ${gateway.configPath}.`);
   }
+  const gatewayDeviceIdentity = loadGatewayDeviceIdentity();
+  if (!gatewayDeviceIdentity) {
+    console.warn(
+      `[bridge] OpenClaw device identity not found at ${DEVICE_IDENTITY_PATH}; device-signed connect may fail on newer gateways.`
+    );
+  }
+
+  if (runtimeConfig.managedConfigUsed && runtimeConfig.appUrl) {
+    console.log(`[bridge] refreshed broker URLs from ${runtimeConfig.appUrl}`);
+  } else if (runtimeConfig.managedConfigError) {
+    console.warn(
+      `[bridge] failed to refresh broker URLs from app URL; using local/state broker config (${runtimeConfig.managedConfigError})`
+    );
+  }
+
+  try {
+    await runBridgePreflight({
+      brokerWs,
+      gatewayUrl: gateway.gatewayUrl,
+      gatewayConfigPath: gateway.configPath,
+    });
+  } catch (err) {
+    const failure = classifyBridgeFailure({ err });
+    updateBridgeStatus({
+      status: 'error',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: failure.errorCode,
+      lastErrorClass: failure.failureClass,
+      lastErrorMessage: failure.message,
+      hint: failure.hint,
+      consecutiveFailures: 0,
+      pid: process.pid,
+    });
+    throw new Error(`Bridge preflight failed (${failure.failureClass}): ${failure.message}. ${failure.hint}`);
+  }
+
+  updateBridgeStatus({
+    status: 'starting',
+    deviceId,
+    brokerWs,
+    brokerHttp,
+    gatewayUrl: gateway.gatewayUrl,
+    lastErrorCode: '',
+    lastErrorClass: '',
+    lastErrorMessage: '',
+    consecutiveFailures: 0,
+    pid: process.pid,
+    startedAt: bridgeNowIso(),
+  });
 
   console.log(`Starting OpenClaw bridge: device=${deviceId}`);
   console.log(`Local gateway: ${gateway.gatewayUrl}`);
   console.log(`Broker WS: ${brokerWs}`);
 
   const activeGatewaySockets = new Map();
+  const reconnectState = {
+    attempt: 0,
+    timer: null,
+    stopped: false,
+    lastFailure: null,
+  };
   const brokerPath = (() => {
     try {
       return new URL(brokerWs).pathname || '';
@@ -785,27 +1218,196 @@ async function startOpenclawBridge(flags) {
     return null;
   };
 
+  const scheduleReconnect = () => {
+    if (reconnectState.stopped || reconnectState.timer) return;
+    reconnectState.attempt += 1;
+    const failure =
+      reconnectState.lastFailure ||
+      classifyBridgeFailure({ reason: 'connection closed without classified error' });
+    const delayMs = computeReconnectDelayMs(reconnectState.attempt, failure.baseDelayMs);
+
+    console.warn(
+      `[bridge] reconnect scheduled in ${delayMs}ms (attempt ${reconnectState.attempt}, class=${failure.failureClass}, code=${failure.errorCode})`
+    );
+
+    updateBridgeStatus({
+      status: 'reconnecting',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: failure.errorCode,
+      lastErrorClass: failure.failureClass,
+      lastErrorMessage: failure.message,
+      hint: failure.hint,
+      consecutiveFailures: reconnectState.attempt,
+      pid: process.pid,
+    });
+
+    reconnectState.timer = setTimeout(() => {
+      reconnectState.timer = null;
+      connectBroker();
+    }, delayMs);
+  };
+
   const connectBroker = () => {
     const wsUrl = new URL(brokerWs);
     wsUrl.searchParams.set('token', deviceToken);
 
     const brokerSocket = new WebSocket(wsUrl.toString());
     let actionCableHeartbeat = null;
+
+    const clearChallengeTimer = (sessionBridge) => {
+      if (sessionBridge && sessionBridge.connectChallengeTimer) {
+        clearTimeout(sessionBridge.connectChallengeTimer);
+        sessionBridge.connectChallengeTimer = null;
+      }
+    };
+
+    const queueConnectUntilChallenge = (sessionId, sessionBridge, frame) => {
+      if (!sessionBridge || typeof frame !== 'string' || !frame) return;
+      if (!Array.isArray(sessionBridge.pendingConnectFrames)) {
+        sessionBridge.pendingConnectFrames = [];
+      }
+      if (sessionBridge.pendingConnectFrames.includes(frame)) {
+        return;
+      }
+      sessionBridge.pendingConnectFrames.push(frame);
+
+      if (sessionBridge.connectChallengeTimer) {
+        return;
+      }
+
+      sessionBridge.connectChallengeTimer = setTimeout(() => {
+        sessionBridge.connectChallengeTimer = null;
+        const hasPending = Array.isArray(sessionBridge.pendingConnectFrames)
+          ? sessionBridge.pendingConnectFrames.length > 0
+          : false;
+        if (!hasPending || sessionBridge.connectNonce) {
+          return;
+        }
+        console.error(
+          `[bridge] gateway.connect_challenge_timeout ${sessionId} (${String(BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS)}ms)`
+        );
+        sendBrokerPayload(brokerSocket, {
+          action: 'log',
+          type: 'log',
+          sessionId,
+          level: 'error',
+          message: `Gateway challenge timeout (${String(BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS)}ms) for session ${sessionId}`,
+        });
+        try {
+          sessionBridge.socket?.close(4009, 'connect_challenge_timeout');
+        } catch {
+          // no-op
+        }
+      }, BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS);
+    };
+
+    const flushPendingConnectFrames = (sessionId, sessionBridge) => {
+      if (!sessionBridge || !sessionBridge.connectNonce) return;
+      const pending = Array.isArray(sessionBridge.pendingConnectFrames)
+        ? sessionBridge.pendingConnectFrames.splice(0, sessionBridge.pendingConnectFrames.length)
+        : [];
+      if (pending.length === 0) {
+        clearChallengeTimer(sessionBridge);
+        return;
+      }
+
+      clearChallengeTimer(sessionBridge);
+      for (const pendingFrame of pending) {
+        const prepared = prepareGatewayFrameForLocalGateway(pendingFrame, gateway, {
+          connectNonce: sessionBridge.connectNonce,
+          deviceIdentity: gatewayDeviceIdentity,
+        });
+        if (!prepared.frameText || prepared.waitForChallenge) {
+          continue;
+        }
+        const result = forwardFrameToSession(sessionBridge, prepared.frameText);
+        if (result === 'queued') {
+          console.log(`[bridge] client.frame queued after challenge ${sessionId}`);
+        } else if (result === 'dropped') {
+          console.log(`[bridge] client.frame dropped after challenge ${sessionId}`);
+        } else {
+          console.log(`[bridge] client.frame sent after challenge ${sessionId}`);
+        }
+      }
+    };
+
     const setupGatewaySession = (sessionId, sessionBridge) => {
       if (!sessionBridge || !sessionBridge.socket) return;
       const gatewaySocket = sessionBridge.socket;
+      if (typeof sessionBridge.connectNonce !== 'string') {
+        sessionBridge.connectNonce = '';
+      }
+      if (!Array.isArray(sessionBridge.pendingConnectFrames)) {
+        sessionBridge.pendingConnectFrames = [];
+      }
+      let connectTimeout = setTimeout(() => {
+        if (gatewaySocket.readyState !== WebSocket.CONNECTING) return;
+        console.error(
+          `[bridge] gateway.connect_timeout ${sessionId} (${String(BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS)}ms)`
+        );
+        sendBrokerPayload(brokerSocket, {
+          action: 'log',
+          type: 'log',
+          sessionId,
+          level: 'error',
+          message: `Gateway connect timeout (${String(BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS)}ms) for session ${sessionId}`,
+        });
+        try {
+          gatewaySocket.close(4008, 'gateway_connect_timeout');
+        } catch {
+          // no-op
+        }
+      }, BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS);
 
       gatewaySocket.on('open', () => {
+        if (connectTimeout) {
+          clearTimeout(connectTimeout);
+          connectTimeout = null;
+        }
         console.log(`[bridge] gateway.open ${sessionId}`);
         flushSessionQueue(sessionBridge);
       });
 
       gatewaySocket.on('message', (gatewayRaw) => {
         const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
+        const gatewayPayload = parseJsonPayload(frame);
+        if (gatewayPayload?.event === 'connect.challenge') {
+          const nonce =
+            gatewayPayload.payload && typeof gatewayPayload.payload.nonce === 'string'
+              ? gatewayPayload.payload.nonce.trim()
+              : '';
+          if (!nonce) {
+            console.error(`[bridge] gateway.connect.challenge missing nonce for ${sessionId}`);
+            sendBrokerPayload(brokerSocket, {
+              action: 'log',
+              type: 'log',
+              sessionId,
+              level: 'error',
+              message: `Gateway connect challenge missing nonce for session ${sessionId}`,
+            });
+            try {
+              gatewaySocket.close(1008, 'connect_challenge_missing_nonce');
+            } catch {
+              // no-op
+            }
+          } else {
+            sessionBridge.connectNonce = nonce;
+            flushPendingConnectFrames(sessionId, sessionBridge);
+          }
+        }
         sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
       });
 
       gatewaySocket.on('close', (code, reason) => {
+        if (connectTimeout) {
+          clearTimeout(connectTimeout);
+          connectTimeout = null;
+        }
+        clearChallengeTimer(sessionBridge);
         const reasonText = reason ? reason.toString() : '';
         console.log(
           `[bridge] gateway.close ${sessionId} code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`
@@ -821,6 +1423,10 @@ async function startOpenclawBridge(flags) {
       });
 
       gatewaySocket.on('error', (err) => {
+        if (connectTimeout && gatewaySocket.readyState !== WebSocket.CONNECTING) {
+          clearTimeout(connectTimeout);
+          connectTimeout = null;
+        }
         console.error(`[bridge] gateway.error ${sessionId}: ${String(err)}`);
         sendBrokerPayload(brokerSocket, {
           action: 'log',
@@ -846,6 +1452,8 @@ async function startOpenclawBridge(flags) {
 
     brokerSocket.on('open', () => {
       console.log('[bridge] Connected to managed broker.');
+      reconnectState.attempt = 0;
+      reconnectState.lastFailure = null;
       if (!actionCableMode) return;
       brokerSocket.send(
         JSON.stringify({
@@ -856,6 +1464,20 @@ async function startOpenclawBridge(flags) {
       actionCableHeartbeat = setInterval(() => {
         sendBrokerPayload(brokerSocket, { action: 'heartbeat' });
       }, 15000);
+      updateBridgeStatus({
+        status: 'connected',
+        deviceId,
+        brokerWs,
+        brokerHttp,
+        gatewayUrl: gateway.gatewayUrl,
+        lastConnectedAt: bridgeNowIso(),
+        lastErrorCode: '',
+        lastErrorClass: '',
+        lastErrorMessage: '',
+        hint: '',
+        consecutiveFailures: 0,
+        pid: process.pid,
+      });
     });
 
     brokerSocket.on('message', (rawData) => {
@@ -868,12 +1490,61 @@ async function startOpenclawBridge(flags) {
       }
 
       if (payload.type === 'broker.disconnect') {
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: String(payload.reason || 'unauthorized'),
+          forceClass: 'auth_rejected',
+        });
+        reconnectState.stopped = true;
         console.error(`[bridge] Broker rejected connection: ${String(payload.reason || 'unauthorized')}`);
+        console.error(`[bridge] ${reconnectState.lastFailure.hint}`);
+        updateBridgeStatus({
+          status: 'error',
+          deviceId,
+          brokerWs,
+          brokerHttp,
+          gatewayUrl: gateway.gatewayUrl,
+          lastDisconnectAt: bridgeNowIso(),
+          lastErrorCode: reconnectState.lastFailure.errorCode,
+          lastErrorClass: reconnectState.lastFailure.failureClass,
+          lastErrorMessage: reconnectState.lastFailure.message,
+          hint: reconnectState.lastFailure.hint,
+          consecutiveFailures: reconnectState.attempt + 1,
+          pid: process.pid,
+        });
+        try {
+          brokerSocket.close(4001, 'auth_rejected');
+        } catch {
+          // no-op
+        }
         return;
       }
 
       if (payload.type === 'broker.reject_subscription') {
         console.error('[bridge] Broker rejected DeviceChannel subscription.');
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: 'broker rejected DeviceChannel subscription',
+          forceClass: 'auth_rejected',
+        });
+        reconnectState.stopped = true;
+        updateBridgeStatus({
+          status: 'error',
+          deviceId,
+          brokerWs,
+          brokerHttp,
+          gatewayUrl: gateway.gatewayUrl,
+          lastDisconnectAt: bridgeNowIso(),
+          lastErrorCode: reconnectState.lastFailure.errorCode,
+          lastErrorClass: reconnectState.lastFailure.failureClass,
+          lastErrorMessage: reconnectState.lastFailure.message,
+          hint: reconnectState.lastFailure.hint,
+          consecutiveFailures: reconnectState.attempt + 1,
+          pid: process.pid,
+        });
+        try {
+          brokerSocket.close(4002, 'subscription_rejected');
+        } catch {
+          // no-op
+        }
         return;
       }
 
@@ -897,8 +1568,19 @@ async function startOpenclawBridge(flags) {
         console.log(`[bridge] client.frame ${sessionId}`);
         const sessionBridge = getOrCreateGatewaySession(sessionId);
         if (!sessionBridge) return;
-        const frameWithAuth = injectGatewayAuth(frame, gateway);
-        const result = forwardFrameToSession(sessionBridge, frameWithAuth);
+        const prepared = prepareGatewayFrameForLocalGateway(frame, gateway, {
+          connectNonce: sessionBridge.connectNonce,
+          deviceIdentity: gatewayDeviceIdentity,
+        });
+        if (prepared.waitForChallenge) {
+          queueConnectUntilChallenge(sessionId, sessionBridge, frame);
+          console.log(`[bridge] client.frame waiting for challenge ${sessionId}`);
+          return;
+        }
+        if (!prepared.frameText) {
+          return;
+        }
+        const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued ${sessionId}`);
         } else if (result === 'dropped') {
@@ -912,6 +1594,7 @@ async function startOpenclawBridge(flags) {
         console.log(`[bridge] client.close ${sessionId}`);
         const sessionBridge = activeGatewaySockets.get(sessionId);
         if (sessionBridge && sessionBridge.socket) {
+          clearChallengeTimer(sessionBridge);
           activeGatewaySockets.delete(sessionId);
           sessionBridge.socket.close(1000, 'client_closed');
         }
@@ -924,8 +1607,10 @@ async function startOpenclawBridge(flags) {
         clearInterval(actionCableHeartbeat);
         actionCableHeartbeat = null;
       }
-      console.log(`[bridge] Broker disconnected (${code}) ${reason.toString()}`);
+      const reasonText = reason ? reason.toString() : '';
+      console.log(`[bridge] Broker disconnected (${code}) ${reasonText}`);
       for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
+        clearChallengeTimer(sessionBridge);
         activeGatewaySockets.delete(sessionId);
         try {
           sessionBridge.socket.close(1001, 'broker_disconnected');
@@ -933,13 +1618,48 @@ async function startOpenclawBridge(flags) {
           // no-op
         }
       }
-      setTimeout(connectBroker, 2000);
+
+      if (reconnectState.stopped) {
+        return;
+      }
+
+      if (!reconnectState.lastFailure) {
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: `socket closed code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`,
+        });
+      }
+      scheduleReconnect();
     });
 
     brokerSocket.on('error', (err) => {
-      console.error('[bridge] Broker socket error:', err);
+      reconnectState.lastFailure = classifyBridgeFailure({ err });
+      console.error(
+        `[bridge] Broker socket error [${reconnectState.lastFailure.failureClass}/${reconnectState.lastFailure.errorCode}]: ${reconnectState.lastFailure.message}`
+      );
+      console.error(`[bridge] ${reconnectState.lastFailure.hint}`);
+    });
+  };
+
+  const markStopped = (signal) => {
+    reconnectState.stopped = true;
+    if (reconnectState.timer) {
+      clearTimeout(reconnectState.timer);
+      reconnectState.timer = null;
+    }
+    updateBridgeStatus({
+      status: 'stopped',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      stopSignal: signal,
+      pid: process.pid,
     });
+    process.exit(0);
   };
+  process.once('SIGINT', () => markStopped('SIGINT'));
+  process.once('SIGTERM', () => markStopped('SIGTERM'));
 
   connectBroker();
   await new Promise(() => {});
@@ -1030,25 +1750,13 @@ async function pairAndStartOpenclawBridge(flags) {
   }
 
   if (detach) {
-    const args = [
-      process.argv[1],
-      'openclaw',
-      'bridge',
-      '--broker-http',
-      managedConfig.brokerHttpUrl,
-      '--broker-ws',
-      brokerWs,
-      '--device-id',
-      deviceId,
-      '--device-token',
-      deviceToken,
-    ];
-    const child = spawn(process.execPath, args, {
-      detached: true,
-      stdio: 'ignore',
+    const pid = startBridgeDetachedProcess({
+      'broker-http': managedConfig.brokerHttpUrl,
+      'broker-ws': brokerWs,
+      'device-id': deviceId,
+      'device-token': deviceToken,
     });
-    child.unref();
-    console.log(`Bridge started in background (pid: ${child.pid}).`);
+    console.log(`Bridge started in background (pid: ${pid}).`);
     return;
   }
 
@@ -1116,6 +1824,69 @@ async function createOpenclawInviteLink(flags) {
   }
 }
 
+function printOpenclawBridgeStatus(flags) {
+  const bridgeState = readBridgeState();
+  const runtimeStatus = readBridgeStatus();
+  const jsonOutput = isTruthyFlag(flags.json);
+  const redactToken = (value) => {
+    const text = String(value || '').trim();
+    if (!text) return '';
+    if (text.length <= 12) return '***';
+    return `${text.slice(0, 6)}...${text.slice(-6)}`;
+  };
+
+  const payload = {
+    bridgeStatePath: resolveBridgeStatePath(),
+    bridgeStatusPath: resolveBridgeStatusPath(),
+    bridgeState: {
+      brokerHttp: String(bridgeState.brokerHttp || ''),
+      brokerWs: String(bridgeState.brokerWs || ''),
+      deviceId: String(bridgeState.deviceId || ''),
+      deviceToken: redactToken(bridgeState.deviceToken),
+      claimedAt: bridgeState.claimedAt || null,
+      expiresAt: bridgeState.expiresAt || null,
+    },
+    runtime: runtimeStatus,
+  };
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('Oomi Bridge Status');
+  console.log('------------------');
+  console.log(`Bridge state: ${payload.bridgeStatePath}`);
+  console.log(`Runtime status: ${payload.bridgeStatusPath}`);
+  console.log(`Device: ${payload.bridgeState.deviceId || 'not paired'}`);
+  console.log(`Broker HTTP: ${payload.bridgeState.brokerHttp || 'not configured'}`);
+  console.log(`Broker WS: ${payload.bridgeState.brokerWs || 'not configured'}`);
+  if (payload.bridgeState.deviceToken) {
+    console.log(`Device token: ${payload.bridgeState.deviceToken}`);
+  }
+  if (payload.runtime && typeof payload.runtime === 'object' && Object.keys(payload.runtime).length > 0) {
+    console.log(`Runtime state: ${String(payload.runtime.status || 'unknown')}`);
+    if (payload.runtime.lastConnectedAt) {
+      console.log(`Last connected: ${payload.runtime.lastConnectedAt}`);
+    }
+    if (payload.runtime.lastDisconnectAt) {
+      console.log(`Last disconnected: ${payload.runtime.lastDisconnectAt}`);
+    }
+    if (payload.runtime.lastErrorClass || payload.runtime.lastErrorCode || payload.runtime.lastErrorMessage) {
+      console.log(
+        `Last error: ${String(payload.runtime.lastErrorClass || 'unknown')}/${String(payload.runtime.lastErrorCode || 'UNKNOWN')} ${String(payload.runtime.lastErrorMessage || '').trim()}`
+      );
+    }
+    if (payload.runtime.hint) {
+      console.log(`Hint: ${payload.runtime.hint}`);
+    }
+    return;
+  }
+
+  console.log('Runtime state: no bridge runtime status recorded yet.');
+  console.log('Run: oomi openclaw bridge --app-url https://www.oomi.ai');
+}
+
 function printOpenclawPluginSetup(flags) {
   const bridgeState = readBridgeState();
   const backendUrl = String(
@@ -1215,6 +1986,13 @@ async function main() {
   }
 
   if (command === 'openclaw' && subcommand === 'bridge') {
+    if (Boolean(args.flags.detach)) {
+      const detachedFlags = { ...args.flags };
+      delete detachedFlags.detach;
+      const pid = startBridgeDetachedProcess(detachedFlags);
+      console.log(`Bridge started in background (pid: ${pid}).`);
+      return;
+    }
     await startOpenclawBridge(args.flags);
     return;
   }
@@ -1229,6 +2007,11 @@ async function main() {
     return;
   }
 
+  if (command === 'openclaw' && subcommand === 'status') {
+    printOpenclawBridgeStatus(args.flags);
+    return;
+  }
+
   if (command === 'openclaw' && subcommand === 'plugin') {
     printOpenclawPluginSetup(args.flags);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Oomi CLI for OpenClaw setup",
   "bin": {
     "oomi": "bin/oomi-ai.js"