oomi-ai 0.2.7 → 0.2.12

package/bin/oomi-ai.js

@@ -2,10 +2,11 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { createPrivateKey, createPublicKey, randomUUID, sign as cryptoSign } from 'crypto';
 import net from 'net';
 import { lookup as dnsLookup } from 'dns/promises';
+import { fileURLToPath } from 'url';
 import WebSocket from 'ws';
 import { ensureSessionBridge, forwardFrameToSession, flushSessionQueue } from './sessionBridgeState.js';
 
@@ -26,6 +27,11 @@ const BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS = parsePositiveInteger(
   process.env.OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS,
   3000
 );
+const BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS = parsePositiveInteger(
+  process.env.OOMI_BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
+  30000
+);
+const BRIDGE_LAUNCHD_LABEL = 'ai.oomi.bridge';
 const DEVICE_IDENTITY_PATH = path.join(os.homedir(), '.openclaw', 'identity', 'device.json');
 const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
 
@@ -151,8 +157,10 @@ Commands:
   openclaw install
     Install agent instructions and the Oomi skill into OpenClaw.
 
-  openclaw bridge
-    Start local OpenClaw-to-Oomi managed broker bridge.
+  openclaw bridge [start|ensure|stop|restart|ps]
+    Manage local OpenClaw-to-Oomi bridge lifecycle (singleton).
+  openclaw bridge service [install|start|stop|restart|status|uninstall]
+    Manage macOS launchd bridge supervision.
 
   openclaw pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
@@ -204,8 +212,17 @@ function readFile(filePath) {
   return fs.readFileSync(filePath, 'utf-8');
 }
 
-function writeFile(filePath, content) {
-  fs.writeFileSync(filePath, content);
+function writeFile(filePath, content, options = undefined) {
+  fs.writeFileSync(filePath, content, options);
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
 }
 
 function resolveWorkspace() {
@@ -558,6 +575,18 @@ function resolveBridgeStatusPath() {
   return path.join(os.homedir(), '.openclaw', 'oomi-bridge-status.json');
 }
 
+function resolveBridgeLockPath() {
+  return path.join(os.homedir(), '.openclaw', 'oomi-bridge.lock');
+}
+
+function resolveBridgeLiveLogPath() {
+  return path.join(os.homedir(), '.openclaw', 'logs', 'oomi-bridge-live.log');
+}
+
+function resolveBridgeLaunchAgentPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${BRIDGE_LAUNCHD_LABEL}.plist`);
+}
+
 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)}`;
@@ -608,6 +637,158 @@ function updateBridgeStatus(partial) {
   return next;
 }
 
+function normalizeBridgeMetrics(value) {
+  if (!value || typeof value !== 'object') return {};
+  const next = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const parsed = Number(raw);
+    next[key] = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+  }
+  return next;
+}
+
+function incrementBridgeMetric(metricKey, amount = 1) {
+  const normalizedKey = String(metricKey || '').trim();
+  if (!normalizedKey) return;
+  const delta = Number(amount);
+  if (!Number.isFinite(delta) || delta <= 0) return;
+
+  const current = readBridgeStatus();
+  const metrics = normalizeBridgeMetrics(current.metrics);
+  metrics[normalizedKey] = (metrics[normalizedKey] || 0) + Math.floor(delta);
+  updateBridgeStatus({ metrics });
+}
+
+function normalizePid(value) {
+  const pid = Number(value);
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  return pid;
+}
+
+function isPidAlive(pid) {
+  const normalized = normalizePid(pid);
+  if (!normalized) return false;
+  try {
+    process.kill(normalized, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isBridgeWorkerCommand(command) {
+  const text = String(command || '').trim().toLowerCase();
+  if (!text.includes('openclaw bridge')) return false;
+  if (/\bopenclaw\s+bridge\s+(ps|stop|restart|ensure)\b/.test(text)) return false;
+  if (/\bopenclaw\s+bridge\s+start\b/.test(text)) return true;
+  if (/\bopenclaw\s+bridge(\s+--|$)/.test(text)) return true;
+  return false;
+}
+
+function isBridgeProcess(pid) {
+  const normalized = normalizePid(pid);
+  if (!normalized) return false;
+  if (!isPidAlive(normalized)) return false;
+
+  try {
+    const result = spawnSync('ps', ['-p', String(normalized), '-o', 'command='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const command = String(result.stdout || '').trim();
+    if (!command) return true;
+    return isBridgeWorkerCommand(command);
+  } catch {
+    return true;
+  }
+}
+
+function readBridgeLock() {
+  return readJsonSafe(resolveBridgeLockPath()) || {};
+}
+
+function clearStaleBridgeLock() {
+  const lockPath = resolveBridgeLockPath();
+  if (!fs.existsSync(lockPath)) return;
+  const lock = readBridgeLock();
+  const lockPid = normalizePid(lock.pid);
+  if (lockPid && isBridgeProcess(lockPid)) return;
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    // no-op
+  }
+}
+
+function findRunningBridgeProcess() {
+  clearStaleBridgeLock();
+
+  const lock = readBridgeLock();
+  const lockPid = normalizePid(lock.pid);
+  if (lockPid && isBridgeProcess(lockPid)) {
+    return {
+      pid: lockPid,
+      source: 'lock',
+      deviceId: typeof lock.deviceId === 'string' ? lock.deviceId : '',
+    };
+  }
+
+  const status = readBridgeStatus();
+  const statusPid = normalizePid(status.pid);
+  if (statusPid && isBridgeProcess(statusPid)) {
+    return {
+      pid: statusPid,
+      source: 'status',
+      deviceId: typeof status.deviceId === 'string' ? status.deviceId : '',
+    };
+  }
+
+  return null;
+}
+
+function acquireBridgeLock(deviceId) {
+  const lockPath = resolveBridgeLockPath();
+  ensureDir(path.dirname(lockPath));
+  const payload = {
+    pid: process.pid,
+    deviceId,
+    acquiredAt: bridgeNowIso(),
+  };
+
+  const writeLock = () => writeFile(lockPath, JSON.stringify(payload, null, 2) + '\n', { flag: 'wx' });
+
+  try {
+    writeLock();
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : '';
+    if (code !== 'EEXIST') {
+      throw err;
+    }
+    clearStaleBridgeLock();
+    const existing = findRunningBridgeProcess();
+    if (existing && existing.pid !== process.pid) {
+      throw new Error(
+        `Bridge already running (pid ${existing.pid})${existing.deviceId ? ` for device ${existing.deviceId}` : ''}.`
+      );
+    }
+    writeLock();
+  }
+
+  const release = () => {
+    const current = readBridgeLock();
+    const currentPid = normalizePid(current.pid);
+    if (currentPid && currentPid !== process.pid) return;
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // no-op
+    }
+  };
+
+  process.once('exit', release);
+  return release;
+}
+
 async function claimBridgeDeviceToken({ brokerHttp, pairCode, deviceId }) {
   const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/claim`, {
     method: 'POST',
@@ -768,11 +949,20 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
       return { frameText, waitForChallenge: false };
     }
 
-    const params = frame.params && typeof frame.params === 'object' ? frame.params : {};
+    const rawParams = frame.params && typeof frame.params === 'object' ? frame.params : {};
+    const params = {};
 
-    const client = params.client && typeof params.client === 'object' ? params.client : {};
-    const incomingClientId = typeof client.id === 'string' ? client.id.trim().toLowerCase() : '';
-    const incomingClientMode = typeof client.mode === 'string' ? client.mode.trim().toLowerCase() : '';
+    params.minProtocol = Number.isInteger(rawParams.minProtocol) && rawParams.minProtocol >= 1
+      ? rawParams.minProtocol
+      : 3;
+    params.maxProtocol = Number.isInteger(rawParams.maxProtocol) && rawParams.maxProtocol >= 1
+      ? rawParams.maxProtocol
+      : 3;
+
+    const clientInput = rawParams.client && typeof rawParams.client === 'object' ? rawParams.client : {};
+    const client = {};
+    const incomingClientId = typeof clientInput.id === 'string' ? clientInput.id.trim().toLowerCase() : '';
+    const incomingClientMode = typeof clientInput.mode === 'string' ? clientInput.mode.trim().toLowerCase() : '';
     const proxiedBrowserClient =
       incomingClientMode === 'webchat' ||
       incomingClientId === 'webchat-ui' ||
@@ -784,18 +974,32 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
     // so Control UI/webchat Origin checks don't reject proxied sessions.
     client.id = proxiedBrowserClient
       ? 'node-host'
-      : (typeof client.id === 'string' && client.id.trim() ? client.id.trim() : 'node-host');
-    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;
+      : (typeof clientInput.id === 'string' && clientInput.id.trim() ? clientInput.id.trim() : 'node-host');
+    client.version = typeof clientInput.version === 'string' && clientInput.version.trim() ? clientInput.version.trim() : '0.1.0';
+    client.platform = proxiedBrowserClient
+      ? process.platform
+      : (typeof clientInput.platform === 'string' && clientInput.platform.trim() ? clientInput.platform.trim() : process.platform);
     client.mode = proxiedBrowserClient
       ? 'backend'
-      : (typeof client.mode === 'string' && client.mode.trim() ? client.mode.trim() : 'backend');
+      : (typeof clientInput.mode === 'string' && clientInput.mode.trim() ? clientInput.mode.trim() : 'backend');
+    if (typeof clientInput.displayName === 'string' && clientInput.displayName.trim()) {
+      client.displayName = clientInput.displayName.trim();
+    }
+    if (typeof clientInput.deviceFamily === 'string' && clientInput.deviceFamily.trim()) {
+      client.deviceFamily = clientInput.deviceFamily.trim();
+    }
+    if (typeof clientInput.modelIdentifier === 'string' && clientInput.modelIdentifier.trim()) {
+      client.modelIdentifier = clientInput.modelIdentifier.trim();
+    }
+    if (typeof clientInput.instanceId === 'string' && clientInput.instanceId.trim()) {
+      client.instanceId = clientInput.instanceId.trim();
+    }
     params.client = client;
 
-    params.role = typeof params.role === 'string' && params.role.trim() ? params.role.trim() : 'operator';
+    params.role = typeof rawParams.role === 'string' && rawParams.role.trim() ? rawParams.role.trim() : 'operator';
 
-    const existingScopes = Array.isArray(params.scopes)
-      ? params.scopes.filter((value) => typeof value === 'string' && value.trim())
+    const existingScopes = Array.isArray(rawParams.scopes)
+      ? rawParams.scopes.filter((value) => typeof value === 'string' && value.trim())
       : [];
     const requiredScopes = ['operator.read', 'operator.write'];
     for (const scope of requiredScopes) {
@@ -805,14 +1009,28 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
     }
     params.scopes = existingScopes;
 
-    if (!Array.isArray(params.caps)) {
-      params.caps = [];
-    }
-    if (!Array.isArray(params.commands)) {
-      params.commands = [];
+    params.caps = Array.isArray(rawParams.caps)
+      ? rawParams.caps.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+
+    params.commands = Array.isArray(rawParams.commands)
+      ? rawParams.commands.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+
+    if (rawParams.permissions && typeof rawParams.permissions === 'object') {
+      const permissions = {};
+      for (const [key, value] of Object.entries(rawParams.permissions)) {
+        const normalizedKey = typeof key === 'string' ? key.trim() : '';
+        if (!normalizedKey || typeof value !== 'boolean') continue;
+        permissions[normalizedKey] = value;
+      }
+      if (Object.keys(permissions).length > 0) {
+        params.permissions = permissions;
+      }
     }
-    if (!params.permissions || typeof params.permissions !== 'object') {
-      params.permissions = {};
+
+    if (typeof rawParams.pathEnv === 'string') {
+      params.pathEnv = rawParams.pathEnv;
     }
 
     const auth = {};
@@ -825,16 +1043,23 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
       params.auth = auth;
     }
 
+    if (typeof rawParams.locale === 'string' && rawParams.locale.trim()) {
+      params.locale = rawParams.locale;
+    }
+    if (typeof rawParams.userAgent === 'string' && rawParams.userAgent.trim()) {
+      params.userAgent = rawParams.userAgent;
+    }
+
     if (deviceIdentity) {
       if (!connectNonce) {
-        return { frameText: null, waitForChallenge: true };
+        return { frameText, 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 nonceForSignature = connectNonce;
 
       const payload = buildDeviceAuthPayloadV3({
         deviceId: deviceIdentity.deviceId,
@@ -844,7 +1069,7 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
         scopes: existingScopes,
         signedAtMs,
         token: tokenForSignature,
-        nonce: connectNonce,
+        nonce: nonceForSignature,
         platform: client.platform,
         deviceFamily: typeof client.deviceFamily === 'string' ? client.deviceFamily : '',
       });
@@ -854,7 +1079,7 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
         publicKey: publicKeyRawBase64UrlFromPem(deviceIdentity.publicKeyPem),
         signature,
         signedAt: signedAtMs,
-        nonce: connectNonce,
+        nonce: nonceForSignature,
       };
     }
 
@@ -873,6 +1098,53 @@ function parseJsonPayload(raw) {
   }
 }
 
+function extractCorrelationId(params) {
+  if (!params || typeof params !== 'object') return '';
+  if (typeof params.correlationId === 'string' && params.correlationId.trim()) {
+    return params.correlationId.trim();
+  }
+  const metadata = params.metadata;
+  if (metadata && typeof metadata === 'object' && typeof metadata.correlationId === 'string' && metadata.correlationId.trim()) {
+    return metadata.correlationId.trim();
+  }
+  return '';
+}
+
+function extractGatewayRequestMeta(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.type !== 'req') return null;
+  const requestId = typeof payload.id === 'string' ? payload.id.trim() : '';
+  const method = typeof payload.method === 'string' ? payload.method.trim() : '';
+  if (!requestId || !method) return null;
+
+  const params = payload.params && typeof payload.params === 'object' ? payload.params : {};
+  const correlationId = extractCorrelationId(params);
+  return { requestId, method, correlationId };
+}
+
+function extractGatewayResponseMeta(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.type !== 'res') return null;
+  const requestId = typeof payload.id === 'string' ? payload.id.trim() : '';
+  if (!requestId) return null;
+  return {
+    requestId,
+    ok: payload.ok === true,
+  };
+}
+
+function isGatewayRunStartedFrame(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return false;
+  if (payload.type !== 'event' || payload.event !== 'agent') return false;
+  const body = payload.payload;
+  if (!body || typeof body !== 'object') return false;
+  if (body.stream !== 'lifecycle') return false;
+  return body.data && typeof body.data === 'object' && body.data.phase === 'start';
+}
+
 function bridgeNowIso() {
   return new Date().toISOString();
 }
@@ -1030,13 +1302,260 @@ function buildBridgeDetachArgs(rawFlags = {}) {
 }
 
 function startBridgeDetachedProcess(rawFlags = {}) {
+  const existing = findRunningBridgeProcess();
+  if (existing) {
+    return {
+      pid: existing.pid,
+      alreadyRunning: true,
+    };
+  }
+
   const args = buildBridgeDetachArgs(rawFlags);
+  const logPath = resolveBridgeLiveLogPath();
+  ensureDir(path.dirname(logPath));
+  fs.appendFileSync(logPath, `[${new Date().toISOString()}] [bridge-supervisor] starting detached bridge\n`);
+  const logFd = fs.openSync(logPath, 'a');
   const child = spawn(process.execPath, args, {
     detached: true,
-    stdio: 'ignore',
+    stdio: ['ignore', logFd, logFd],
   });
   child.unref();
-  return child.pid;
+  try {
+    fs.closeSync(logFd);
+  } catch {
+    // no-op
+  }
+  return {
+    pid: child.pid,
+    alreadyRunning: false,
+  };
+}
+
+function listBridgeProcessPids() {
+  const pids = new Set();
+  const addPid = (value) => {
+    const pid = normalizePid(value);
+    if (!pid || pid === process.pid) return;
+    if (!isBridgeProcess(pid)) return;
+    pids.add(pid);
+  };
+
+  const lock = readBridgeLock();
+  addPid(lock.pid);
+
+  const status = readBridgeStatus();
+  addPid(status.pid);
+
+  try {
+    const result = spawnSync('ps', ['-Ao', 'pid=,command='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const output = String(result.stdout || '');
+    for (const rawLine of output.split('\n')) {
+      const line = rawLine.trim();
+      if (!line) continue;
+      const match = line.match(/^(\d+)\s+(.+)$/);
+      if (!match) continue;
+      const pid = Number(match[1]);
+      const command = String(match[2] || '');
+      if (!isBridgeWorkerCommand(command)) continue;
+      addPid(pid);
+    }
+  } catch {
+    // best-effort process scan
+  }
+
+  return Array.from(pids).sort((a, b) => a - b);
+}
+
+async function waitForBridgePidsToExit(pids, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const alive = pids.filter((pid) => isBridgeProcess(pid));
+    if (alive.length === 0) return [];
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return pids.filter((pid) => isBridgeProcess(pid));
+}
+
+async function stopBridgeProcesses() {
+  const targets = listBridgeProcessPids();
+  if (targets.length === 0) {
+    clearStaleBridgeLock();
+    updateBridgeStatus({
+      status: 'stopped',
+      stopSignal: 'none',
+      lastDisconnectAt: bridgeNowIso(),
+      pid: null,
+    });
+    return {
+      stopped: [],
+      forceKilled: [],
+      found: [],
+    };
+  }
+
+  for (const pid of targets) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // no-op
+    }
+  }
+
+  let remaining = await waitForBridgePidsToExit(targets, 2500);
+  const forceKilled = [];
+  if (remaining.length > 0) {
+    for (const pid of remaining) {
+      try {
+        process.kill(pid, 'SIGKILL');
+        forceKilled.push(pid);
+      } catch {
+        // no-op
+      }
+    }
+    remaining = await waitForBridgePidsToExit(remaining, 1000);
+  }
+
+  clearStaleBridgeLock();
+
+  const stopped = targets.filter((pid) => !remaining.includes(pid));
+  updateBridgeStatus({
+    status: 'stopped',
+    stopSignal: forceKilled.length > 0 ? 'SIGKILL' : 'SIGTERM',
+    lastDisconnectAt: bridgeNowIso(),
+    pid: null,
+  });
+
+  return {
+    stopped,
+    forceKilled,
+    found: targets,
+    stillAlive: remaining,
+  };
+}
+
+function assertMacOSLaunchdAvailable() {
+  if (process.platform !== 'darwin') {
+    throw new Error('Bridge service manager is only supported on macOS (launchd).');
+  }
+  if (typeof process.getuid !== 'function') {
+    throw new Error('Cannot resolve current UID for launchd domain.');
+  }
+}
+
+function launchctlDomain() {
+  assertMacOSLaunchdAvailable();
+  return `gui/${String(process.getuid())}`;
+}
+
+function launchctlServiceTarget() {
+  return `${launchctlDomain()}/${BRIDGE_LAUNCHD_LABEL}`;
+}
+
+function runLaunchctl(args, { allowFailure = false } = {}) {
+  const result = spawnSync('launchctl', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const status = Number.isInteger(result.status) ? result.status : 1;
+  const stdout = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '').trim();
+  if (status !== 0 && !allowFailure) {
+    throw new Error(
+      `launchctl ${args.join(' ')} failed (${status}): ${stderr || stdout || 'unknown launchctl error'}`
+    );
+  }
+  return { status, stdout, stderr };
+}
+
+function buildBridgeLaunchAgentPlist() {
+  const scriptPath = (() => {
+    try {
+      return fs.realpathSync(process.argv[1]);
+    } catch {
+      return process.argv[1];
+    }
+  })();
+  const programArgs = [process.execPath, scriptPath, 'openclaw', 'bridge', 'start'];
+  const bridgeLogPath = resolveBridgeLiveLogPath();
+  const argsXml = programArgs.map((arg) => `<string>${xmlEscape(arg)}</string>`).join('\n      ');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(BRIDGE_LAUNCHD_LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+      ${argsXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(os.homedir())}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>OOMI_SKIP_UPDATE_CHECK</key>
+    <string>1</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(bridgeLogPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(bridgeLogPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+function readBridgeLaunchdStatus() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  const target = launchctlServiceTarget();
+  const printResult = runLaunchctl(['print', target], { allowFailure: true });
+  const loaded = printResult.status === 0;
+  const output = [printResult.stdout, printResult.stderr].filter(Boolean).join('\n');
+  const pidMatch = output.match(/\bpid\s*=\s*(\d+)/);
+  const lastExitMatch = output.match(/\blast exit code\s*=\s*(-?\d+)/i);
+
+  return {
+    plistPath,
+    target,
+    installed: fs.existsSync(plistPath),
+    loaded,
+    pid: pidMatch ? Number(pidMatch[1]) : null,
+    running: Boolean(pidMatch && Number(pidMatch[1]) > 0),
+    lastExitCode: lastExitMatch ? Number(lastExitMatch[1]) : null,
+    printOutput: output,
+  };
+}
+
+function startBridgeLaunchdService() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  if (!fs.existsSync(plistPath)) {
+    throw new Error('Bridge service is not installed. Run: oomi openclaw bridge service install');
+  }
+  const domain = launchctlDomain();
+  const target = launchctlServiceTarget();
+  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
+  runLaunchctl(['bootstrap', domain, plistPath]);
+  runLaunchctl(['enable', target], { allowFailure: true });
+  runLaunchctl(['kickstart', '-k', target], { allowFailure: true });
+}
+
+async function stopBridgeLaunchdService() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  const domain = launchctlDomain();
+  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
+  return stopBridgeProcesses();
 }
 
 async function resolveBridgeRuntimeConfig(flags, bridgeState) {
@@ -1077,6 +1596,13 @@ async function resolveBridgeRuntimeConfig(flags, bridgeState) {
 }
 
 async function startOpenclawBridge(flags) {
+  const runningBridge = findRunningBridgeProcess();
+  if (runningBridge && runningBridge.pid !== process.pid) {
+    throw new Error(
+      `Bridge already running (pid ${runningBridge.pid})${runningBridge.deviceId ? ` for device ${runningBridge.deviceId}` : ''}.`
+    );
+  }
+
   const bridgeState = readBridgeState();
   const runtimeConfig = await resolveBridgeRuntimeConfig(flags, bridgeState);
   const brokerHttp = runtimeConfig.brokerHttp;
@@ -1084,6 +1610,7 @@ async function startOpenclawBridge(flags) {
   const deviceId = resolveDeviceId(flags, bridgeState);
   const pairCode = String(flags['pair-code'] || '').trim().toUpperCase();
   const explicitDeviceToken = String(flags['device-token'] || '').trim();
+  const releaseBridgeLock = acquireBridgeLock(deviceId);
   let deviceToken = explicitDeviceToken;
   if (!deviceToken && String(bridgeState.deviceId || '').trim() === deviceId) {
     deviceToken = String(bridgeState.deviceToken || '').trim();
@@ -1209,6 +1736,188 @@ async function startOpenclawBridge(flags) {
     );
   };
 
+  const sendGatewayAck = (brokerSocket, {
+    sessionId,
+    requestId = '',
+    method = '',
+    correlationId = '',
+    stage = 'unknown',
+  }) => {
+    if (!sessionId) return;
+    if (requestId) {
+      const sessionBridge = activeGatewaySockets.get(sessionId);
+      if (sessionBridge && sessionBridge.pendingRequests instanceof Map) {
+        const pending = sessionBridge.pendingRequests.get(requestId);
+        if (pending) {
+          pending.lastSuccessfulHop = stage;
+          sessionBridge.pendingRequests.set(requestId, pending);
+        }
+      }
+    }
+    sendBrokerPayload(brokerSocket, {
+      action: 'gateway_ack',
+      type: 'gateway.ack',
+      sessionId,
+      requestId,
+      method,
+      correlationId,
+      stage,
+      ts: bridgeNowIso(),
+    });
+  };
+
+  const sendGatewayErrorResponse = (
+    brokerSocket,
+    {
+      sessionId,
+      requestMeta,
+      code = 'gateway_error',
+      message = 'Gateway request failed',
+      lastSuccessfulHop = '',
+      retryable = false,
+      details = null,
+    }
+  ) => {
+    if (!sessionId || !requestMeta || !requestMeta.requestId) return;
+    const errorPayload = {
+      code,
+      message,
+      correlationId: requestMeta.correlationId || '',
+    };
+    if (lastSuccessfulHop) {
+      errorPayload.lastSuccessfulHop = lastSuccessfulHop;
+    }
+    if (retryable === true) {
+      errorPayload.retryable = true;
+    }
+    if (details && typeof details === 'object') {
+      errorPayload.details = details;
+    }
+    const responseFrame = {
+      type: 'res',
+      id: requestMeta.requestId,
+      ok: false,
+      error: errorPayload,
+    };
+    sendBrokerPayload(brokerSocket, {
+      action: 'gateway_frame',
+      type: 'gateway.frame',
+      sessionId,
+      frame: JSON.stringify(responseFrame),
+    });
+  };
+
+  const classifyGatewayClose = (code, reasonText) => {
+    const reasonLower = String(reasonText || '').toLowerCase();
+    if (code === 1008 && reasonLower.includes('invalid connect params')) {
+      return {
+        errorCode: 'gateway_invalid_connect_params',
+        retryable: false,
+      };
+    }
+    if (code === 1008) {
+      return {
+        errorCode: 'gateway_policy_violation',
+        retryable: false,
+      };
+    }
+    if (code === 1003 || code === 1002) {
+      return {
+        errorCode: 'gateway_protocol_error',
+        retryable: false,
+      };
+    }
+    if (code === 1006) {
+      return {
+        errorCode: 'gateway_abnormal_close',
+        retryable: true,
+      };
+    }
+    return {
+      errorCode: 'gateway_closed',
+      retryable: true,
+    };
+  };
+
+  const clearPendingRequestTimeout = (sessionBridge, requestId) => {
+    if (!sessionBridge || !(sessionBridge.pendingRequestTimers instanceof Map)) return;
+    const existingTimer = sessionBridge.pendingRequestTimers.get(requestId);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+      sessionBridge.pendingRequestTimers.delete(requestId);
+    }
+  };
+
+  const clearAllPendingRequestTimeouts = (sessionBridge) => {
+    if (!sessionBridge || !(sessionBridge.pendingRequestTimers instanceof Map)) return;
+    for (const timer of sessionBridge.pendingRequestTimers.values()) {
+      clearTimeout(timer);
+    }
+    sessionBridge.pendingRequestTimers.clear();
+  };
+
+  const startPendingRequestTimeout = (brokerSocket, sessionId, sessionBridge, requestMeta) => {
+    if (!sessionBridge || !requestMeta || !requestMeta.requestId) return;
+    if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+      sessionBridge.pendingRequestTimers = new Map();
+    }
+    clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+    const timer = setTimeout(() => {
+      const pending = sessionBridge.pendingRequests instanceof Map
+        ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+        : null;
+      if (!pending) {
+        clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+        return;
+      }
+
+      if (requestMeta.method === 'connect') {
+        incrementBridgeMetric('connect_timeout_count');
+      } else if (requestMeta.method === 'chat.send') {
+        incrementBridgeMetric('chat_send_timeout_count');
+      } else {
+        incrementBridgeMetric('gateway_request_timeout_count');
+      }
+
+      const lastSuccessfulHop = typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+        ? pending.lastSuccessfulHop
+        : 'bridge.forwarded';
+      sendGatewayAck(brokerSocket, {
+        sessionId,
+        requestId: pending.requestId,
+        method: pending.method,
+        correlationId: pending.correlationId,
+        stage: 'gateway.timeout',
+      });
+      sendBrokerPayload(brokerSocket, {
+        action: 'log',
+        type: 'log',
+        sessionId,
+        level: 'warn',
+        message: `Gateway request timeout (${pending.method} ${pending.requestId}) after ${String(BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS)}ms`,
+      });
+      sendGatewayErrorResponse(brokerSocket, {
+        sessionId,
+        requestMeta: pending,
+        code: 'gateway_timeout',
+        message: `Gateway request timeout (${pending.method}) after ${String(BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS)}ms`,
+        lastSuccessfulHop,
+        retryable: true,
+        details: {
+          method: pending.method,
+          timeoutMs: BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
+        },
+      });
+
+      if (sessionBridge.pendingRequests instanceof Map) {
+        sessionBridge.pendingRequests.delete(pending.requestId);
+      }
+      clearPendingRequestTimeout(sessionBridge, pending.requestId);
+    }, BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS);
+
+    sessionBridge.pendingRequestTimers.set(requestMeta.requestId, timer);
+  };
+
   const parseBrokerEnvelope = (raw) => {
     const payload = parseJsonPayload(raw);
     if (!payload) return null;
@@ -1236,6 +1945,7 @@ async function startOpenclawBridge(flags) {
   const scheduleReconnect = () => {
     if (reconnectState.stopped || reconnectState.timer) return;
     reconnectState.attempt += 1;
+    incrementBridgeMetric('bridge_reconnect_scheduled_count');
     const failure =
       reconnectState.lastFailure ||
       classifyBridgeFailure({ reason: 'connection closed without classified error' });
@@ -1332,20 +2042,102 @@ async function startOpenclawBridge(flags) {
 
       clearChallengeTimer(sessionBridge);
       for (const pendingFrame of pending) {
+        const requestMeta = extractGatewayRequestMeta(pendingFrame);
         const prepared = prepareGatewayFrameForLocalGateway(pendingFrame, gateway, {
           connectNonce: sessionBridge.connectNonce,
           deviceIdentity: gatewayDeviceIdentity,
         });
         if (!prepared.frameText || prepared.waitForChallenge) {
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'bridge.waiting_for_challenge';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped connect request after challenge handling.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+          }
           continue;
         }
         const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued after challenge ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.queued',
+            });
+          }
         } else if (result === 'dropped') {
           console.log(`[bridge] client.frame dropped after challenge ${sessionId}`);
+          incrementBridgeMetric('bridge_drop_count');
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'bridge.waiting_for_challenge';
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request because gateway socket is not open.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+          }
         } else {
           console.log(`[bridge] client.frame sent after challenge ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.forwarded',
+            });
+          }
         }
       }
     };
@@ -1359,11 +2151,21 @@ async function startOpenclawBridge(flags) {
       if (!Array.isArray(sessionBridge.pendingConnectFrames)) {
         sessionBridge.pendingConnectFrames = [];
       }
+      if (!(sessionBridge.pendingRequests instanceof Map)) {
+        sessionBridge.pendingRequests = new Map();
+      }
+      if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+        sessionBridge.pendingRequestTimers = new Map();
+      }
+      if (typeof sessionBridge.lastChatCorrelationId !== 'string') {
+        sessionBridge.lastChatCorrelationId = '';
+      }
       let connectTimeout = setTimeout(() => {
         if (gatewaySocket.readyState !== WebSocket.CONNECTING) return;
         console.error(
           `[bridge] gateway.connect_timeout ${sessionId} (${String(BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS)}ms)`
         );
+        incrementBridgeMetric('gateway_connect_timeout_count');
         sendBrokerPayload(brokerSocket, {
           action: 'log',
           type: 'log',
@@ -1391,6 +2193,7 @@ async function startOpenclawBridge(flags) {
         const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
         const gatewayPayload = parseJsonPayload(frame);
         if (gatewayPayload?.event === 'connect.challenge') {
+          console.log(`[bridge] gateway.connect.challenge ${sessionId}`);
           const nonce =
             gatewayPayload.payload && typeof gatewayPayload.payload.nonce === 'string'
               ? gatewayPayload.payload.nonce.trim()
@@ -1414,6 +2217,35 @@ async function startOpenclawBridge(flags) {
             flushPendingConnectFrames(sessionId, sessionBridge);
           }
         }
+
+        const responseMeta = extractGatewayResponseMeta(frame);
+        if (responseMeta && sessionBridge.pendingRequests instanceof Map) {
+          const requestMeta = sessionBridge.pendingRequests.get(responseMeta.requestId);
+          if (requestMeta) {
+            clearPendingRequestTimeout(sessionBridge, responseMeta.requestId);
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: responseMeta.ok ? 'gateway.accepted' : 'gateway.rejected',
+            });
+            if (!responseMeta.ok) {
+              incrementBridgeMetric('gateway_rejected_count');
+            }
+            sessionBridge.pendingRequests.delete(responseMeta.requestId);
+          }
+        }
+
+        if (isGatewayRunStartedFrame(frame)) {
+          sendGatewayAck(brokerSocket, {
+            sessionId,
+            method: 'chat.send',
+            correlationId: sessionBridge.lastChatCorrelationId || '',
+            stage: 'run.started',
+          });
+        }
+
         sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
       });
 
@@ -1424,9 +2256,41 @@ async function startOpenclawBridge(flags) {
         }
         clearChallengeTimer(sessionBridge);
         const reasonText = reason ? reason.toString() : '';
+        const closeMeta = classifyGatewayClose(code, reasonText);
         console.log(
           `[bridge] gateway.close ${sessionId} code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`
         );
+        if (sessionBridge.pendingRequests instanceof Map) {
+          for (const requestMeta of sessionBridge.pendingRequests.values()) {
+            if (!requestMeta || typeof requestMeta !== 'object') continue;
+            const lastSuccessfulHop = typeof requestMeta.lastSuccessfulHop === 'string' && requestMeta.lastSuccessfulHop
+              ? requestMeta.lastSuccessfulHop
+              : 'bridge.forwarded';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId || '',
+              method: requestMeta.method || '',
+              correlationId: requestMeta.correlationId || '',
+              stage: 'gateway.closed',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: closeMeta.errorCode,
+              message: reasonText
+                ? `Gateway closed (${String(code)}): ${reasonText}`
+                : `Gateway closed (${String(code)})`,
+              lastSuccessfulHop,
+              retryable: closeMeta.retryable,
+              details: {
+                closeCode: code,
+                closeReason: reasonText,
+              },
+            });
+          }
+          sessionBridge.pendingRequests.clear();
+        }
+        clearAllPendingRequestTimeouts(sessionBridge);
         activeGatewaySockets.delete(sessionId);
         sendBrokerPayload(brokerSocket, {
           action: 'gateway_closed',
@@ -1583,6 +2447,22 @@ async function startOpenclawBridge(flags) {
         console.log(`[bridge] client.frame ${sessionId}`);
         const sessionBridge = getOrCreateGatewaySession(sessionId);
         if (!sessionBridge) return;
+        const requestMeta = extractGatewayRequestMeta(frame);
+        if (requestMeta) {
+          if (!(sessionBridge.pendingRequests instanceof Map)) {
+            sessionBridge.pendingRequests = new Map();
+          }
+          if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+            sessionBridge.pendingRequestTimers = new Map();
+          }
+          sessionBridge.pendingRequests.set(requestMeta.requestId, {
+            ...requestMeta,
+            lastSuccessfulHop: 'broker.accepted',
+          });
+          if (requestMeta.method === 'chat.send' && requestMeta.correlationId) {
+            sessionBridge.lastChatCorrelationId = requestMeta.correlationId;
+          }
+        }
         const prepared = prepareGatewayFrameForLocalGateway(frame, gateway, {
           connectNonce: sessionBridge.connectNonce,
           deviceIdentity: gatewayDeviceIdentity,
@@ -1590,16 +2470,103 @@ async function startOpenclawBridge(flags) {
         if (prepared.waitForChallenge) {
           queueConnectUntilChallenge(sessionId, sessionBridge, frame);
           console.log(`[bridge] client.frame waiting for challenge ${sessionId}`);
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.waiting_for_challenge',
+            });
+          }
           return;
         }
         if (!prepared.frameText) {
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'broker.accepted';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request before forwarding to gateway.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+          }
           return;
         }
         const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.queued',
+            });
+          }
         } else if (result === 'dropped') {
           console.log(`[bridge] client.frame dropped (socket not open) ${sessionId}`);
+          incrementBridgeMetric('bridge_drop_count');
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'broker.accepted';
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request because gateway socket is not open.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+          }
+        } else if (requestMeta) {
+          startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          sendGatewayAck(brokerSocket, {
+            sessionId,
+            requestId: requestMeta.requestId,
+            method: requestMeta.method,
+            correlationId: requestMeta.correlationId,
+            stage: 'bridge.forwarded',
+          });
         }
         return;
       }
@@ -1610,6 +2577,10 @@ async function startOpenclawBridge(flags) {
         const sessionBridge = activeGatewaySockets.get(sessionId);
         if (sessionBridge && sessionBridge.socket) {
           clearChallengeTimer(sessionBridge);
+          if (sessionBridge.pendingRequests instanceof Map) {
+            sessionBridge.pendingRequests.clear();
+          }
+          clearAllPendingRequestTimeouts(sessionBridge);
           activeGatewaySockets.delete(sessionId);
           sessionBridge.socket.close(1000, 'client_closed');
         }
@@ -1624,8 +2595,13 @@ async function startOpenclawBridge(flags) {
       }
       const reasonText = reason ? reason.toString() : '';
       console.log(`[bridge] Broker disconnected (${code}) ${reasonText}`);
+      incrementBridgeMetric('bridge_disconnect_count');
       for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
         clearChallengeTimer(sessionBridge);
+        if (sessionBridge.pendingRequests instanceof Map) {
+          sessionBridge.pendingRequests.clear();
+        }
+        clearAllPendingRequestTimeouts(sessionBridge);
         activeGatewaySockets.delete(sessionId);
         try {
           sessionBridge.socket.close(1001, 'broker_disconnected');
@@ -1647,6 +2623,7 @@ async function startOpenclawBridge(flags) {
     });
 
     brokerSocket.on('error', (err) => {
+      incrementBridgeMetric('bridge_socket_error_count');
       reconnectState.lastFailure = classifyBridgeFailure({ err });
       console.error(
         `[bridge] Broker socket error [${reconnectState.lastFailure.failureClass}/${reconnectState.lastFailure.errorCode}]: ${reconnectState.lastFailure.message}`
@@ -1671,6 +2648,7 @@ async function startOpenclawBridge(flags) {
       stopSignal: signal,
       pid: process.pid,
     });
+    releaseBridgeLock();
     process.exit(0);
   };
   process.once('SIGINT', () => markStopped('SIGINT'));
@@ -1765,13 +2743,17 @@ async function pairAndStartOpenclawBridge(flags) {
   }
 
   if (detach) {
-    const pid = startBridgeDetachedProcess({
+    const result = startBridgeDetachedProcess({
       'broker-http': managedConfig.brokerHttpUrl,
       'broker-ws': brokerWs,
       'device-id': deviceId,
       'device-token': deviceToken,
     });
-    console.log(`Bridge started in background (pid: ${pid}).`);
+    if (result.alreadyRunning) {
+      console.log(`Bridge already running (pid: ${result.pid}).`);
+      return;
+    }
+    console.log(`Bridge started in background (pid: ${result.pid}).`);
     return;
   }
 
@@ -1895,6 +2877,16 @@ function printOpenclawBridgeStatus(flags) {
     if (payload.runtime.hint) {
       console.log(`Hint: ${payload.runtime.hint}`);
     }
+    if (payload.runtime.metrics && typeof payload.runtime.metrics === 'object') {
+      const metrics = normalizeBridgeMetrics(payload.runtime.metrics);
+      const metricPairs = Object.entries(metrics);
+      if (metricPairs.length > 0) {
+        console.log('Metrics:');
+        for (const [name, value] of metricPairs) {
+          console.log(`  ${name}: ${value}`);
+        }
+      }
+    }
     return;
   }
 
@@ -1969,6 +2961,169 @@ function printOpenclawPluginSetup(flags) {
   }
 }
 
+async function handleBridgeServiceCommand(actionRaw = '', flags = {}) {
+  assertMacOSLaunchdAvailable();
+  const action = String(actionRaw || 'status').trim().toLowerCase();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+
+  if (action === 'install') {
+    ensureDir(path.dirname(plistPath));
+    writeFile(plistPath, buildBridgeLaunchAgentPlist());
+    console.log(`Installed bridge launchd plist: ${plistPath}`);
+    if (isTruthyFlag(flags['no-start'])) {
+      console.log('Service install complete. Start with: oomi openclaw bridge service start');
+      return;
+    }
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_start_count');
+    console.log(`Bridge service started: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'uninstall') {
+    await stopBridgeLaunchdService();
+    if (fs.existsSync(plistPath)) {
+      fs.unlinkSync(plistPath);
+    }
+    console.log(`Removed bridge launchd plist: ${plistPath}`);
+    return;
+  }
+
+  if (action === 'start') {
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_start_count');
+    console.log(`Bridge service started: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'stop') {
+    const stopped = await stopBridgeLaunchdService();
+    if (Array.isArray(stopped.found) && stopped.found.length > 0) {
+      console.log(`Stopped bridge workers: ${stopped.stopped.join(', ') || 'none'}.`);
+    } else {
+      console.log('No bridge workers running.');
+    }
+    console.log(`Bridge service stopped: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'restart') {
+    await stopBridgeLaunchdService();
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_restart_count');
+    console.log(`Bridge service restarted: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'status') {
+    const status = readBridgeLaunchdStatus();
+    console.log('Bridge Service Status');
+    console.log('---------------------');
+    console.log(`Label: ${BRIDGE_LAUNCHD_LABEL}`);
+    console.log(`Target: ${status.target}`);
+    console.log(`Plist: ${status.plistPath}`);
+    console.log(`Installed: ${status.installed ? 'yes' : 'no'}`);
+    console.log(`Loaded: ${status.loaded ? 'yes' : 'no'}`);
+    console.log(`Running: ${status.running ? 'yes' : 'no'}`);
+    if (status.pid) {
+      console.log(`PID: ${status.pid}`);
+    }
+    if (status.lastExitCode !== null) {
+      console.log(`Last exit code: ${status.lastExitCode}`);
+    }
+    return;
+  }
+
+  throw new Error(
+    `Unknown bridge service action: ${action}. Use: oomi openclaw bridge service [install|start|stop|restart|status|uninstall]`
+  );
+}
+
+async function startBridgeLifecycle(flags = {}) {
+  if (Boolean(flags.detach)) {
+    const detachedFlags = { ...flags };
+    delete detachedFlags.detach;
+    const result = startBridgeDetachedProcess(detachedFlags);
+    if (result.alreadyRunning) {
+      incrementBridgeMetric('duplicate_start_attempt_count');
+      console.log(`Bridge already running (pid: ${result.pid}).`);
+      return;
+    }
+    incrementBridgeMetric('bridge_start_count');
+    console.log(`Bridge started in background (pid: ${result.pid}).`);
+    return;
+  }
+
+  const running = findRunningBridgeProcess();
+  if (running) {
+    incrementBridgeMetric('duplicate_start_attempt_count');
+    console.log(
+      `Bridge already running (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}.`
+    );
+    return;
+  }
+
+  incrementBridgeMetric('bridge_start_count');
+  await startOpenclawBridge(flags);
+}
+
+async function handleBridgeLifecycleCommand(flags = {}, actionRaw = '') {
+  const action = String(actionRaw || 'start').trim().toLowerCase();
+
+  if (action === 'start' || action === 'ensure') {
+    await startBridgeLifecycle(flags);
+    return;
+  }
+
+  if (action === 'ps') {
+    const pids = listBridgeProcessPids();
+    if (pids.length === 0) {
+      console.log('No bridge processes running.');
+      return;
+    }
+    console.log(`Bridge processes: ${pids.join(', ')}`);
+    return;
+  }
+
+  if (action === 'stop') {
+    const result = await stopBridgeProcesses();
+    if (result.found.length === 0) {
+      console.log('No bridge processes running.');
+      return;
+    }
+    console.log(`Stopped bridge processes: ${result.stopped.join(', ') || 'none'}.`);
+    if (result.forceKilled.length > 0) {
+      console.log(`Force-killed bridge processes: ${result.forceKilled.join(', ')}.`);
+    }
+    if (Array.isArray(result.stillAlive) && result.stillAlive.length > 0) {
+      throw new Error(`Failed to stop bridge processes: ${result.stillAlive.join(', ')}`);
+    }
+    return;
+  }
+
+  if (action === 'restart') {
+    incrementBridgeMetric('bridge_restart_count');
+    const result = await stopBridgeProcesses();
+    if (result.found.length > 0) {
+      console.log(`Stopped bridge processes: ${result.stopped.join(', ') || 'none'}.`);
+      if (result.forceKilled.length > 0) {
+        console.log(`Force-killed bridge processes: ${result.forceKilled.join(', ')}.`);
+      }
+    } else {
+      console.log('No existing bridge process found; starting fresh bridge.');
+    }
+    if (Array.isArray(result.stillAlive) && result.stillAlive.length > 0) {
+      throw new Error(`Failed to stop bridge processes: ${result.stillAlive.join(', ')}`);
+    }
+    await startBridgeLifecycle(flags);
+    return;
+  }
+
+  throw new Error(
+    `Unknown bridge action: ${action}. Use: oomi openclaw bridge [start|ensure|stop|restart|ps]`
+  );
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   const command = args.command;
@@ -2001,14 +3156,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}).`);
+    const bridgeAction = String(args.positionals[0] || 'start').trim().toLowerCase();
+    if (bridgeAction === 'service') {
+      const serviceAction = args.positionals[1] || 'status';
+      await handleBridgeServiceCommand(serviceAction, args.flags);
       return;
     }
-    await startOpenclawBridge(args.flags);
+    await handleBridgeLifecycleCommand(args.flags, bridgeAction);
     return;
   }
 
@@ -2051,7 +3205,24 @@ async function main() {
   process.exit(1);
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
-  process.exit(1);
-});
+const __currentFilePath = fileURLToPath(import.meta.url);
+const __invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+const __isDirectExecution = Boolean(__invokedPath) && __invokedPath === path.resolve(__currentFilePath);
+
+if (__isDirectExecution) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}
+
+export {
+  prepareGatewayFrameForLocalGateway,
+  classifyBridgeFailure,
+  computeReconnectDelayMs,
+  extractGatewayRequestMeta,
+  extractGatewayResponseMeta,
+  isGatewayRunStartedFrame,
+  isBridgeWorkerCommand,
+  parsePositiveInteger,
+};