clawdex-mobile 5.0.6 → 5.0.8-internal.0

package/README.md

@@ -38,7 +38,7 @@ npm install -g clawdex-mobile@latest
 clawdex init
 ```
 
-Then open the mobile app and connect using the printed bridge URL/token.
+Then open the mobile app and connect using the printed bridge URL/token or pairing QR.
 `clawdex init` now writes config, starts the bridge in the background, and returns you to the shell. Bridge logs go to `.bridge.log`.
 
 The npm package is bridge-only. It does not install Expo or the mobile source tree. On supported macOS, Linux, and Windows hosts it uses bundled bridge binaries, so normal startup does not compile Rust.

package/docs/setup-and-operations.md

@@ -28,7 +28,7 @@ After `clawdex init`, expected sequence:
 
 1. Secure config is written or reused
 2. The bridge starts in the background
-3. The wizard prints the bridge URL/token for manual mobile pairing
+3. The wizard prints the bridge URL, token, and pairing QR for mobile onboarding
 4. Bridge logs are written to `.bridge.log`
 
 Published npm releases bundle prebuilt bridge binaries for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-armv7l`, and `win32-x64`. On those hosts, normal bridge startup does not require a Rust compile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.0.6",
+  "version": "5.0.8-internal.0",
   "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
   "keywords": [
     "codex",
@@ -19,6 +19,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
   "bin": {
     "clawdex": "./bin/clawdex.js"
   },

package/scripts/setup-wizard.sh

@@ -194,7 +194,7 @@ sync_active_engine_from_selection() {
     return
   fi
 
-  if engine_list_contains "$ACTIVE_ENGINE" "${SELECTED_ENGINES[@]}"; then
+  if selected_engines_contains "$ACTIVE_ENGINE"; then
     return
   fi
 
@@ -215,6 +215,30 @@ format_engine_list() {
   printf '%s' "$result"
 }
 
+selected_engines_contains() {
+  local needle="$1"
+
+  if (( ${#SELECTED_ENGINES[@]} == 0 )); then
+    return 1
+  fi
+
+  engine_list_contains "$needle" "${SELECTED_ENGINES[@]}"
+}
+
+format_selected_engines() {
+  if (( ${#SELECTED_ENGINES[@]} == 0 )); then
+    printf ''
+    return 0
+  fi
+
+  format_engine_list "${SELECTED_ENGINES[@]}"
+}
+
+selected_engines_csv() {
+  local IFS=','
+  printf '%s' "${SELECTED_ENGINES[*]-}"
+}
+
 engine_from_menu_label() {
   case "$1" in
     "Codex")
@@ -957,7 +981,11 @@ print_existing_setup_summary() {
   local harnesses=""
   local source_path=""
   local saved_active_engine="$ACTIVE_ENGINE"
-  local -a saved_selected_engines=("${SELECTED_ENGINES[@]}")
+  local -a saved_selected_engines=()
+
+  if (( ${#SELECTED_ENGINES[@]} > 0 )); then
+    saved_selected_engines=("${SELECTED_ENGINES[@]}")
+  fi
 
   if [[ ! -f "$SECURE_ENV_FILE" ]]; then
     return 1
@@ -971,7 +999,7 @@ print_existing_setup_summary() {
   if [[ -n "$harnesses" ]] && ! parse_existing_engine_list_csv "$harnesses"; then
     harnesses=""
   elif [[ -n "$harnesses" ]]; then
-    harnesses="$(IFS=,; printf '%s' "${SELECTED_ENGINES[*]}")"
+    harnesses="$(selected_engines_csv)"
   fi
   if [[ -z "$harnesses" ]]; then
     harnesses="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ACTIVE_ENGINE")"
@@ -999,7 +1027,10 @@ print_existing_setup_summary() {
   fi
   echo "source: $source_path"
 
-  SELECTED_ENGINES=("${saved_selected_engines[@]}")
+  SELECTED_ENGINES=()
+  if (( ${#saved_selected_engines[@]} > 0 )); then
+    SELECTED_ENGINES=("${saved_selected_engines[@]}")
+  fi
   ACTIVE_ENGINE="$saved_active_engine"
 }
 
@@ -1082,12 +1113,12 @@ choose_bridge_network_mode() {
 choose_runtime_engine() {
   local label=""
   MENU_MULTI_PRESELECTED="Codex"
-  if engine_list_contains "codex" "${SELECTED_ENGINES[@]}"; then
+  if selected_engines_contains "codex"; then
     MENU_MULTI_PRESELECTED="Codex"
   else
     MENU_MULTI_PRESELECTED=""
   fi
-  if engine_list_contains "opencode" "${SELECTED_ENGINES[@]}"; then
+  if selected_engines_contains "opencode"; then
     if [[ -n "$MENU_MULTI_PRESELECTED" ]]; then
       MENU_MULTI_PRESELECTED+=","
     fi
@@ -1101,7 +1132,7 @@ choose_runtime_engine() {
     SELECTED_ENGINES+=("$(engine_from_menu_label "$label")")
   done
   sync_active_engine_from_selection
-  info "Selected harnesses: $(format_engine_list "${SELECTED_ENGINES[@]}")."
+  info "Selected harnesses: $(format_selected_engines)."
 }
 
 infer_network_mode_from_host() {
@@ -1217,6 +1248,11 @@ ensure_opencode_cli() {
 
 ensure_selected_engine_clis() {
   local engine=""
+
+  if (( ${#SELECTED_ENGINES[@]} == 0 )); then
+    abort_wizard "Select at least one harness before continuing."
+  fi
+
   for engine in "${SELECTED_ENGINES[@]}"; do
     case "$engine" in
       codex)
@@ -1613,16 +1649,16 @@ fi
 load_existing_engine_selection
 if [[ "$CONFIG_ACTION" == "keep" ]]; then
   if [[ "$ENGINE_SELECTION_PRESET" == "false" ]]; then
-    info "Keeping existing harnesses: $(format_engine_list "${SELECTED_ENGINES[@]}")."
+    info "Keeping existing harnesses: $(format_selected_engines)."
   else
-    info "Harness selection preset via flag: $(format_engine_list "${SELECTED_ENGINES[@]}")."
+    info "Harness selection preset via flag: $(format_selected_engines)."
   fi
 else
   section "Harnesses"
   if [[ "$ENGINE_SELECTION_PRESET" == "false" ]]; then
     choose_runtime_engine
   else
-    info "Harness selection preset via flag: $(format_engine_list "${SELECTED_ENGINES[@]}")."
+    info "Harness selection preset via flag: $(format_selected_engines)."
   fi
 fi
 
@@ -1652,7 +1688,7 @@ if [[ "$CONFIG_ACTION" != "keep" ]]; then
   esac
 
   section "Write secure config"
-  BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(IFS=,; printf '%s' "${SELECTED_ENGINES[*]}")" "$SCRIPT_DIR/setup-secure-dev.sh"
+  BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(selected_engines_csv)" "$SCRIPT_DIR/setup-secure-dev.sh"
 else
   ok "Keeping existing secure config."
   NETWORK_MODE="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_NETWORK_MODE")"
@@ -1677,10 +1713,10 @@ else
     fi
 
     section "Write secure config"
-    BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(IFS=,; printf '%s' "${SELECTED_ENGINES[*]}")" "$SCRIPT_DIR/setup-secure-dev.sh"
-  elif [[ "$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ENABLED_ENGINES")" != "$(IFS=,; printf '%s' "${SELECTED_ENGINES[*]}")" ]]; then
+    BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(selected_engines_csv)" "$SCRIPT_DIR/setup-secure-dev.sh"
+  elif [[ "$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ENABLED_ENGINES")" != "$(selected_engines_csv)" ]]; then
     section "Write secure config"
-    BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(IFS=,; printf '%s' "${SELECTED_ENGINES[*]}")" "$SCRIPT_DIR/setup-secure-dev.sh"
+    BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(selected_engines_csv)" "$SCRIPT_DIR/setup-secure-dev.sh"
   fi
 fi
 
@@ -1711,7 +1747,7 @@ BRIDGE_PORT="${BRIDGE_PORT:-8787}"
 section "Summary"
 rail_echo "Bridge mode: $NETWORK_MODE"
 rail_echo "Bridge endpoint: http://$BRIDGE_HOST:$BRIDGE_PORT"
-rail_echo "Harnesses: $(format_engine_list "${SELECTED_ENGINES[@]}")"
+rail_echo "Harnesses: $(format_selected_engines)"
 rail_echo "Secure env: $SECURE_ENV_FILE"
 if [[ "$FLOW" == "quickstart" ]]; then
   rail_echo "${DIM}Tip: re-run with Manual mode for full control at each step.${RESET}"

package/scripts/start-bridge-secure.js

@@ -17,6 +17,10 @@ const {
 
 const DEFAULT_HEALTH_TIMEOUT_MS = 15000;
 const DEV_HEALTH_TIMEOUT_MS = 60000;
+let qrcodeTerminal = null;
+let qrcodeTerminalLoaded = false;
+let qrcodeTerminalLoadError = null;
+let pairingQrRenderError = null;
 
 function resolveRootDir() {
   let rootDir = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : path.resolve(__dirname, "..");
@@ -59,6 +63,11 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function readNonEmptyEnv(env, key) {
+  const value = env[key];
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
 function formatHostForUrl(host) {
   if (host.includes(":") && !host.startsWith("[")) {
     return `[${host}]`;
@@ -66,71 +75,148 @@ function formatHostForUrl(host) {
   return host;
 }
 
-function bridgePidFile(rootDir) {
-  return path.join(rootDir, ".bridge.pid");
+function buildBridgeUrl(host, port) {
+  return `http://${formatHostForUrl(host)}:${port}`;
 }
 
-function bridgeLogFile(rootDir) {
-  return path.join(rootDir, ".bridge.log");
+function isUnspecifiedBindHost(host) {
+  const normalized = String(host || "").trim().toLowerCase();
+  return normalized === "0.0.0.0" || normalized === "::" || normalized === "[::]";
 }
 
-function extractLatestPairingQrBlock(logContents) {
-  const lines = logContents.split(/\r?\n/);
-  for (let index = lines.length - 1; index >= 0; index -= 1) {
-    const line = lines[index];
-    if (line.includes("Bridge pairing QR (scan from mobile onboarding):")) {
-      const endIndex = lines.findIndex(
-        (entry, offset) =>
-          offset > index && entry.includes("QR contains bridge URL + token for one-tap onboarding.")
-      );
-      if (endIndex !== -1) {
-        return lines.slice(index, endIndex + 1).join("\n").trimEnd();
-      }
-    }
+function buildPairingPayload(env, endpoint) {
+  const token = readNonEmptyEnv(env, "BRIDGE_AUTH_TOKEN");
+  if (!token || isUnspecifiedBindHost(endpoint.host)) {
+    return null;
+  }
 
-    if (line.includes("Bridge token QR fallback (scan from mobile onboarding):")) {
-      const endIndex = lines.findIndex(
-        (entry, offset) =>
-          offset > index &&
-          entry.includes("Full pairing QR unavailable because BRIDGE_HOST=")
-      );
-      if (endIndex !== -1) {
-        return lines.slice(index, endIndex + 1).join("\n").trimEnd();
-      }
-    }
+  return JSON.stringify({
+    type: "clawdex-bridge-pair",
+    bridgeUrl: buildBridgeUrl(endpoint.host, endpoint.port),
+    bridgeToken: token,
+  });
+}
+
+function buildTokenOnlyPairingPayload(env) {
+  const token = readNonEmptyEnv(env, "BRIDGE_AUTH_TOKEN");
+  if (!token) {
+    return null;
   }
 
-  return null;
+  return JSON.stringify({
+    type: "clawdex-bridge-token",
+    bridgeToken: token,
+  });
 }
 
-function printLatestPairingQr(logPath, startOffset = 0) {
+function loadQrcodeTerminal() {
+  if (qrcodeTerminalLoaded) {
+    return qrcodeTerminal;
+  }
+
+  qrcodeTerminalLoaded = true;
+  try {
+    qrcodeTerminal = require("qrcode-terminal");
+  } catch (error) {
+    qrcodeTerminal = null;
+    qrcodeTerminalLoadError = error;
+  }
+
+  return qrcodeTerminal;
+}
+
+function printPairingQr(env, endpoint) {
+  pairingQrRenderError = null;
+  const qr = loadQrcodeTerminal();
+  if (!qr) {
+    return false;
+  }
+
   try {
-    const raw = fs.readFileSync(logPath, "utf8");
-    const contents = startOffset > 0 ? raw.slice(startOffset) : raw;
-    const qrBlock = extractLatestPairingQrBlock(contents);
-    if (!qrBlock) {
+    const payload = buildPairingPayload(env, endpoint);
+    if (payload) {
+      console.log("");
+      console.log("Bridge pairing QR (scan from mobile onboarding):");
+      qr.generate(payload, { small: true });
+      console.log("QR contains bridge URL + token for one-tap onboarding.");
+      console.log("");
+      return true;
+    }
+
+    const tokenPayload = buildTokenOnlyPairingPayload(env);
+    if (!tokenPayload) {
       return false;
     }
+
     console.log("");
-    console.log(qrBlock);
+    console.log("Bridge token QR fallback (scan from mobile onboarding):");
+    qr.generate(tokenPayload, { small: true });
+    console.log(
+      `Full pairing QR unavailable because BRIDGE_HOST=${endpoint.host} is a bind address. Enter URL manually in onboarding.`
+    );
     console.log("");
     return true;
-  } catch {
+  } catch (error) {
+    pairingQrRenderError = error;
     return false;
   }
 }
 
-async function waitForLatestPairingQr(logPath, startOffset, timeoutMs = 4000) {
-  const startedAt = Date.now();
+function printPairingQrUnavailableMessage(env) {
+  const token = readNonEmptyEnv(env, "BRIDGE_AUTH_TOKEN");
+  if (!token) {
+    console.log(
+      "Pairing QR unavailable because BRIDGE_AUTH_TOKEN is not set. Bridge URL is above for manual onboarding."
+    );
+    return;
+  }
 
-  while (Date.now() - startedAt < timeoutMs) {
-    if (printLatestPairingQr(logPath, startOffset)) {
-      return true;
-    }
-    await sleep(250);
+  if (pairingQrRenderError) {
+    console.log(
+      `Pairing QR unavailable because terminal rendering failed: ${pairingQrRenderError.message}. Bridge URL/token are above for manual onboarding.`
+    );
+    return;
+  }
+
+  if (qrcodeTerminalLoaded && !qrcodeTerminal) {
+    const detail =
+      qrcodeTerminalLoadError && qrcodeTerminalLoadError.message
+        ? ` (${qrcodeTerminalLoadError.message})`
+        : "";
+    console.log(
+      `Pairing QR unavailable because the terminal QR renderer could not be loaded${detail}. Bridge URL/token are above for manual onboarding.`
+    );
+    return;
+  }
+
+  console.log(
+    "Pairing QR unavailable due to an unexpected startup condition. Bridge URL/token are above for manual onboarding."
+  );
+}
+
+function shouldShowPairingQr(env) {
+  const raw = readNonEmptyEnv(env, "BRIDGE_SHOW_PAIRING_QR");
+  return raw ? raw.toLowerCase() !== "false" : true;
+}
+
+function printBridgeAccessDetails(env, endpoint) {
+  const bridgeUrl = buildBridgeUrl(endpoint.host, endpoint.port);
+  console.log(`Bridge URL: ${bridgeUrl}`);
+
+  const token = readNonEmptyEnv(env, "BRIDGE_AUTH_TOKEN");
+  if (token) {
+    console.log(`Bridge token: ${token}`);
   }
 
-  return false;
+  return bridgeUrl;
+}
+
+function bridgePidFile(rootDir) {
+  return path.join(rootDir, ".bridge.pid");
+}
+
+function bridgeLogFile(rootDir) {
+  return path.join(rootDir, ".bridge.log");
 }
 
 function readPidFile(rootDir) {
@@ -317,8 +403,12 @@ async function spawnDetachedAndWait(command, args, options) {
     if (await probeHealth(healthUrl)) {
       console.log(`Bridge already running (pid ${existingPid}).`);
       console.log(`Logs: ${logPath}`);
-      console.log(`Bridge is healthy at http://${formatHostForUrl(host)}:${port}`);
-      printLatestPairingQr(logPath);
+      console.log("Bridge is healthy.");
+      const endpoint = { host, port };
+      printBridgeAccessDetails(env, endpoint);
+      if (shouldShowPairingQr(env) && !printPairingQr(env, endpoint)) {
+        printPairingQrUnavailableMessage(env);
+      }
       return;
     }
   } else if (existingPid) {
@@ -334,7 +424,6 @@ async function spawnDetachedAndWait(command, args, options) {
 
   const output = fs.openSync(logPath, "a");
   const error = fs.openSync(logPath, "a");
-  const logStartOffset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
 
   const child = spawn(command, args, {
     cwd,
@@ -362,9 +451,11 @@ async function spawnDetachedAndWait(command, args, options) {
 
   try {
     const endpoint = await waitForHealth(env, child.pid, healthTimeoutMs);
-    console.log(`Bridge is healthy at http://${formatHostForUrl(endpoint.host)}:${endpoint.port}`);
-    if (!(await waitForLatestPairingQr(logPath, logStartOffset))) {
-      console.log("Pairing QR not found in the new bridge startup log. Open logs if you need to inspect startup output.");
+    console.log("Bridge is healthy.");
+    printBridgeAccessDetails(env, endpoint);
+
+    if (shouldShowPairingQr(env) && !printPairingQr(env, endpoint)) {
+      printPairingQrUnavailableMessage(env);
     }
   } catch (error) {
     removePidFile(rootDir);

package/scripts/stop-services.sh

@@ -73,6 +73,23 @@ extract_env_value() {
   ' "$file"
 }
 
+stop_launchctl_job() {
+  local label="$1"
+
+  if [[ -z "$label" ]] || ! command -v launchctl >/dev/null 2>&1; then
+    return 1
+  fi
+
+  local domain="gui/$(id -u)/$label"
+  if ! launchctl print "$domain" >/dev/null 2>&1; then
+    return 1
+  fi
+
+  echo "Stopping launchd job: $label"
+  launchctl bootout "$domain" >/dev/null 2>&1 || launchctl remove "$label" >/dev/null 2>&1 || true
+  return 0
+}
+
 stop_process_group() {
   local label="$1"
   local pattern="$2"
@@ -111,7 +128,12 @@ stop_process_group() {
 
 echo "Stopping Clawdex services for project: $ROOT_DIR"
 
+BRIDGE_PORT="${BRIDGE_PORT:-$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_PORT" || true)}"
+BRIDGE_PORT="${BRIDGE_PORT:-8787}"
+
 stop_process_group "Expo" "$ROOT_DIR/.*/expo start|$ROOT_DIR/node_modules/.bin/expo start"
+stop_launchctl_job "clawdex.bridge.$BRIDGE_PORT" || true
+stop_process_group "Bridge launcher" "$ROOT_DIR/scripts/start-bridge-secure\\.js|node .*start-bridge-secure\\.js"
 stop_pid_file_process "Rust bridge" "$BRIDGE_PID_FILE" || true
 stop_process_group "Rust bridge" "$ROOT_DIR/services/rust-bridge|codex-rust-bridge|@codex/rust-bridge"
 stop_process_group "Legacy TS bridge" "$ROOT_DIR/services/mac-bridge|@codex/mac-bridge"

package/services/rust-bridge/Cargo.lock

@@ -149,7 +149,7 @@ dependencies = [
 
 [[package]]
 name = "codex-rust-bridge"
-version = "5.0.6"
+version = "5.0.8-internal.0"
 dependencies = [
  "axum",
  "base64",

package/services/rust-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-rust-bridge"
-version = "5.0.6"
+version = "5.0.8-internal.0"
 edition = "2021"
 
 [dependencies]

package/services/rust-bridge/src/main.rs

@@ -2,7 +2,7 @@ use std::{
     collections::{HashMap, HashSet, VecDeque},
     env,
     hash::{Hash, Hasher},
-    io::SeekFrom,
+    io::{SeekFrom, Write},
     path::{Component, Path, PathBuf},
     process::Stdio,
     sync::{
@@ -5404,6 +5404,11 @@ fn build_token_only_pairing_payload(config: &BridgeConfig) -> Option<String> {
     )
 }
 
+fn flush_pairing_output() {
+    let _ = std::io::stdout().flush();
+    let _ = std::io::stderr().flush();
+}
+
 fn maybe_print_pairing_qr(config: &BridgeConfig) {
     if !config.show_pairing_qr {
         return;
@@ -5414,15 +5419,18 @@ fn maybe_print_pairing_qr(config: &BridgeConfig) {
         println!("Bridge pairing QR (scan from mobile onboarding):");
         if let Err(error) = qr2term::print_qr(payload.as_bytes()) {
             eprintln!("failed to render pairing QR: {error}");
+            flush_pairing_output();
             return;
         }
         println!("QR contains bridge URL + token for one-tap onboarding.");
         println!();
+        flush_pairing_output();
         return;
     }
 
     let Some(payload) = build_token_only_pairing_payload(config) else {
         eprintln!("bridge token QR skipped because BRIDGE_AUTH_TOKEN is not set");
+        flush_pairing_output();
         return;
     };
 
@@ -5430,6 +5438,7 @@ fn maybe_print_pairing_qr(config: &BridgeConfig) {
     println!("Bridge token QR fallback (scan from mobile onboarding):");
     if let Err(error) = qr2term::print_qr(payload.as_bytes()) {
         eprintln!("failed to render pairing QR: {error}");
+        flush_pairing_output();
         return;
     }
     println!(
@@ -5437,6 +5446,7 @@ fn maybe_print_pairing_qr(config: &BridgeConfig) {
         config.host
     );
     println!();
+    flush_pairing_output();
 }
 
 fn parse_bool_env(name: &str) -> bool {
@@ -9009,6 +9019,71 @@ mod tests {
         assert!(!constant_time_eq("secret-token", "secret-token-extra"));
     }
 
+    #[test]
+    fn build_pairing_payload_includes_url_and_token_for_connectable_host() {
+        let config = BridgeConfig {
+            host: "127.0.0.1".to_string(),
+            port: 8787,
+            workdir: PathBuf::from("/tmp/workdir"),
+            cli_bin: "codex".to_string(),
+            opencode_cli_bin: "opencode".to_string(),
+            active_engine: BridgeRuntimeEngine::Codex,
+            enabled_engines: vec![BridgeRuntimeEngine::Codex],
+            opencode_host: "127.0.0.1".to_string(),
+            opencode_port: 4090,
+            opencode_server_username: "opencode".to_string(),
+            opencode_server_password: Some("secret-token".to_string()),
+            auth_token: Some("secret-token".to_string()),
+            auth_enabled: true,
+            allow_insecure_no_auth: false,
+            allow_query_token_auth: false,
+            allow_outside_root_cwd: false,
+            disable_terminal_exec: false,
+            terminal_allowed_commands: HashSet::new(),
+            show_pairing_qr: true,
+        };
+
+        let payload = build_pairing_payload(&config).expect("pairing payload");
+        let parsed: Value = serde_json::from_str(&payload).expect("valid json");
+
+        assert_eq!(parsed["type"], "clawdex-bridge-pair");
+        assert_eq!(parsed["bridgeUrl"], "http://127.0.0.1:8787");
+        assert_eq!(parsed["bridgeToken"], "secret-token");
+    }
+
+    #[test]
+    fn build_pairing_payload_uses_token_only_fallback_for_unspecified_bind_host() {
+        let config = BridgeConfig {
+            host: "0.0.0.0".to_string(),
+            port: 8787,
+            workdir: PathBuf::from("/tmp/workdir"),
+            cli_bin: "codex".to_string(),
+            opencode_cli_bin: "opencode".to_string(),
+            active_engine: BridgeRuntimeEngine::Codex,
+            enabled_engines: vec![BridgeRuntimeEngine::Codex],
+            opencode_host: "127.0.0.1".to_string(),
+            opencode_port: 4090,
+            opencode_server_username: "opencode".to_string(),
+            opencode_server_password: Some("secret-token".to_string()),
+            auth_token: Some("secret-token".to_string()),
+            auth_enabled: true,
+            allow_insecure_no_auth: false,
+            allow_query_token_auth: false,
+            allow_outside_root_cwd: false,
+            disable_terminal_exec: false,
+            terminal_allowed_commands: HashSet::new(),
+            show_pairing_qr: true,
+        };
+
+        assert!(build_pairing_payload(&config).is_none());
+
+        let fallback = build_token_only_pairing_payload(&config).expect("token-only payload");
+        let parsed: Value = serde_json::from_str(&fallback).expect("valid json");
+
+        assert_eq!(parsed["type"], "clawdex-bridge-token");
+        assert_eq!(parsed["bridgeToken"], "secret-token");
+    }
+
     #[test]
     fn bridge_config_authorization_validates_header_and_query_token_paths() {
         let base = BridgeConfig {