clawdex-mobile 5.0.5-internal.9 → 5.0.5

package/README.md

@@ -38,7 +38,8 @@ npm install -g clawdex-mobile@latest
 clawdex init
 ```
 
-Then open the mobile app and scan the pairing QR.
+Then open the mobile app and connect using the printed bridge URL/token.
+`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.
 The current interactive setup helpers are still macOS/Linux-oriented.

package/bin/clawdex.js

@@ -12,7 +12,7 @@ function printUsage() {
 Commands:
   init [--no-start] [--engine codex|opencode]
       Run interactive bridge onboarding and secure setup.
-      By default, this also starts the secure bridge in the foreground.
+      By default, this also starts the secure bridge in the background.
       Use --no-start to configure only.
       Use --engine to set the preferred backend written to .env.secure.
 

package/docs/setup-and-operations.md

@@ -27,9 +27,9 @@ If you want only one harness, use `--engine codex` or `--engine opencode`.
 After `clawdex init`, expected sequence:
 
 1. Secure config is written or reused
-2. The bridge starts in the foreground
-3. A pairing QR is printed for the mobile app
-4. Bridge logs stay attached until you stop the process
+2. The bridge starts in the background
+3. The wizard prints the bridge URL/token for manual mobile pairing
+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.
 
@@ -160,6 +160,18 @@ npm run teardown -- --yes
 | `EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE` | suppress insecure-HTTP warning |
 | `EXPO_PUBLIC_PRIVACY_POLICY_URL` | in-app Privacy link |
 | `EXPO_PUBLIC_TERMS_OF_SERVICE_URL` | in-app Terms link |
+| `EXPO_PUBLIC_REVENUECAT_IOS_API_KEY` | RevenueCat public SDK key for iOS tip purchases |
+| `EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY` | RevenueCat public SDK key for Android tip purchases |
+| `EXPO_PUBLIC_REVENUECAT_TEST_STORE_API_KEY` | RevenueCat Test Store public SDK key for Expo Go / Store Client tip testing |
+| `EXPO_PUBLIC_REVENUECAT_TIPS_OFFERING_ID` | optional RevenueCat offering identifier for the tip jar (`current` if omitted) |
+
+If you enable the optional tip jar:
+
+- Configure 4–5 non-subscription products in RevenueCat and attach them to a dedicated Offering
+- Use consumables for repeatable “tip” tiers
+- Enable In-App Purchase for the app’s Apple bundle identifier in App Store Connect / Apple Developer
+- Use the RevenueCat Test Store SDK key in Expo Go; use the real iOS SDK key only in native builds/TestFlight/App Store builds
+- Rebuild the native app after adding `react-native-purchases`
 
 ## Production Readiness Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.0.5-internal.9",
+  "version": "5.0.5",
   "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
   "keywords": [
     "codex",

package/scripts/setup-wizard.sh

@@ -233,6 +233,11 @@ load_existing_engine_selection() {
   local raw=""
   local engine=""
 
+  if [[ "$ENGINE_SELECTION_PRESET" == "true" ]]; then
+    sync_active_engine_from_selection
+    return 0
+  fi
+
   raw="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ENABLED_ENGINES")"
   if [[ -n "$raw" ]] && parse_existing_engine_list_csv "$raw"; then
     engine="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ACTIVE_ENGINE")"
@@ -951,6 +956,8 @@ print_existing_setup_summary() {
   local network_mode=""
   local harnesses=""
   local source_path=""
+  local saved_active_engine="$ACTIVE_ENGINE"
+  local -a saved_selected_engines=("${SELECTED_ENGINES[@]}")
 
   if [[ ! -f "$SECURE_ENV_FILE" ]]; then
     return 1
@@ -991,6 +998,9 @@ print_existing_setup_summary() {
     echo "bridge.token: present"
   fi
   echo "source: $source_path"
+
+  SELECTED_ENGINES=("${saved_selected_engines[@]}")
+  ACTIVE_ENGINE="$saved_active_engine"
 }
 
 require_security_ack() {
@@ -1556,13 +1566,12 @@ confirm_phone_network_ready() {
   esac
 }
 
-start_bridge_foreground() {
-  rail_echo "Starting bridge in foreground."
-  rail_echo "Press Ctrl+C to stop the bridge."
+start_bridge_background() {
+  rail_echo "Starting bridge in background."
   echo ""
   (
     cd "$ROOT_DIR"
-    npm run secure:bridge
+    node "$SCRIPT_DIR/start-bridge-secure.js" --background
   )
 }
 
@@ -1691,6 +1700,7 @@ fi
 
 BRIDGE_HOST="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_HOST")"
 BRIDGE_PORT="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_PORT")"
+BRIDGE_TOKEN="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_AUTH_TOKEN")"
 NETWORK_MODE="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_NETWORK_MODE")"
 if [[ -z "$NETWORK_MODE" ]]; then
   NETWORK_MODE="$(infer_network_mode_from_host "$BRIDGE_HOST")"
@@ -1710,16 +1720,25 @@ fi
 section "Hatch"
 if [[ "$AUTO_START" == "true" ]]; then
   rail_echo "Auto-start enabled."
-  rail_echo "Launching bridge in foreground..."
-  start_bridge_foreground
-  exit $?
+  rail_echo "Launching bridge in background..."
+  start_bridge_background || exit $?
 else
   rail_echo "Auto-start disabled by --no-start."
   rail_echo "Skipping bridge launch."
 fi
 
 section "Next steps"
-rail_echo "1) cd $ROOT_DIR && npm run secure:bridge"
-rail_echo "2) Open the mobile app and use onboarding to connect (URL + token QR)."
+if [[ "$AUTO_START" == "true" ]]; then
+  rail_echo "1) Open the mobile app and use onboarding to connect."
+  rail_echo "Bridge URL: http://$BRIDGE_HOST:$BRIDGE_PORT"
+  if [[ -n "$BRIDGE_TOKEN" ]]; then
+    rail_echo "Bridge token: $BRIDGE_TOKEN"
+  fi
+  rail_echo "Bridge logs: $ROOT_DIR/.bridge.log"
+  rail_echo "2) Stop the bridge later with: clawdex stop"
+else
+  rail_echo "1) cd $ROOT_DIR && npm run secure:bridge"
+  rail_echo "2) Open the mobile app and use onboarding to connect (URL + token QR)."
+fi
 rail_blank
 rail_echo "${DIM}You can rerun this anytime: npm run setup:wizard${RESET}"

package/scripts/start-bridge-secure.js

@@ -3,6 +3,8 @@
 
 const { spawn, spawnSync } = require("node:child_process");
 const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
 const os = require("node:os");
 const path = require("node:path");
 
@@ -13,6 +15,9 @@ const {
   resolveRuntimeTarget,
 } = require("./bridge-binary");
 
+const DEFAULT_HEALTH_TIMEOUT_MS = 15000;
+const DEV_HEALTH_TIMEOUT_MS = 60000;
+
 function resolveRootDir() {
   let rootDir = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : path.resolve(__dirname, "..");
   if (!fs.existsSync(path.join(rootDir, "package.json"))) {
@@ -50,6 +55,103 @@ function readEnvFile(filePath) {
   return nextEnv;
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function formatHostForUrl(host) {
+  if (host.includes(":") && !host.startsWith("[")) {
+    return `[${host}]`;
+  }
+  return host;
+}
+
+function bridgePidFile(rootDir) {
+  return path.join(rootDir, ".bridge.pid");
+}
+
+function bridgeLogFile(rootDir) {
+  return path.join(rootDir, ".bridge.log");
+}
+
+function readPidFile(rootDir) {
+  try {
+    const raw = fs.readFileSync(bridgePidFile(rootDir), "utf8").trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePidFile(rootDir, pid) {
+  fs.writeFileSync(bridgePidFile(rootDir), `${pid}\n`);
+}
+
+function removePidFile(rootDir) {
+  try {
+    fs.unlinkSync(bridgePidFile(rootDir));
+  } catch {}
+}
+
+function isProcessAlive(pid) {
+  if (!pid) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForHealth(env, pid, timeoutMs) {
+  const host = env.BRIDGE_HOST || "127.0.0.1";
+  const port = env.BRIDGE_PORT || "8787";
+  const url = new URL(`http://${formatHostForUrl(host)}:${port}/health`);
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    const ok = await probeHealth(url);
+
+    if (ok) {
+      if (!isProcessAlive(pid)) {
+        throw new Error("bridge health endpoint responded, but the started process already exited");
+      }
+      return { host, port };
+    }
+
+    if (!isProcessAlive(pid)) {
+      throw new Error("bridge process exited before becoming healthy");
+    }
+
+    await sleep(500);
+  }
+
+  throw new Error("bridge health check did not recover in time");
+}
+
+async function probeHealth(url) {
+  const client = url.protocol === "https:" ? https : http;
+  return await new Promise((resolve) => {
+    const req = client.request(
+      url,
+      { method: "GET", timeout: 3000 },
+      (response) => {
+        resolve(response.statusCode === 200);
+        response.resume();
+      }
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.end();
+  });
+}
+
 function commandExists(command) {
   const checker = process.platform === "win32" ? "where" : "which";
   const result = spawnSync(checker, [command], { stdio: "ignore" });
@@ -144,6 +246,69 @@ function spawnAndRelay(command, args, options) {
   });
 }
 
+async function spawnDetachedAndWait(command, args, options) {
+  const { cwd, env, rootDir, healthTimeoutMs } = options;
+  const logPath = bridgeLogFile(rootDir);
+  const host = env.BRIDGE_HOST || "127.0.0.1";
+  const port = env.BRIDGE_PORT || "8787";
+  const healthUrl = new URL(`http://${formatHostForUrl(host)}:${port}/health`);
+  const existingPid = readPidFile(rootDir);
+
+  if (existingPid && isProcessAlive(existingPid)) {
+    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}`);
+      return;
+    }
+  } else if (existingPid) {
+    removePidFile(rootDir);
+  }
+
+  if (await probeHealth(healthUrl)) {
+    console.error(
+      `error: another bridge is already responding at http://${formatHostForUrl(host)}:${port}. Stop it first with 'clawdex stop'.`
+    );
+    process.exit(1);
+  }
+
+  const output = fs.openSync(logPath, "a");
+  const error = fs.openSync(logPath, "a");
+
+  const child = spawn(command, args, {
+    cwd,
+    env,
+    detached: true,
+    stdio: ["ignore", output, error],
+  });
+
+  child.on("error", (spawnError) => {
+    console.error(`error: failed to start ${command}: ${spawnError.message}`);
+    removePidFile(rootDir);
+    process.exit(1);
+  });
+
+  if (!child.pid) {
+    console.error(`error: failed to determine pid for ${command}`);
+    process.exit(1);
+  }
+
+  writePidFile(rootDir, child.pid);
+  child.unref();
+
+  console.log(`Bridge starting in background (pid ${child.pid}).`);
+  console.log(`Logs: ${logPath}`);
+
+  try {
+    const endpoint = await waitForHealth(env, child.pid, healthTimeoutMs);
+    console.log(`Bridge is healthy at http://${formatHostForUrl(endpoint.host)}:${endpoint.port}`);
+  } catch (error) {
+    removePidFile(rootDir);
+    console.error(`error: ${error.message}. Check logs: ${logPath}`);
+    process.exit(1);
+  }
+}
+
 function buildBridgeFromSource(rootDir, env) {
   const cargoCmd = "cargo";
   const args = ["build", "--release", "--locked"];
@@ -163,30 +328,20 @@ function buildBridgeFromSource(rootDir, env) {
   }
 }
 
-function start() {
-  const rootDir = resolveRootDir();
-  const secureEnvFile = path.join(rootDir, ".env.secure");
-  if (!fs.existsSync(secureEnvFile)) {
-    console.error(`error: ${secureEnvFile} not found. Run: npm run secure:setup`);
-    process.exit(1);
-  }
-
-  const fileEnv = readEnvFile(secureEnvFile);
-  const env = { ...fileEnv, ...process.env };
-  const devMode = process.argv.includes("--dev") || env.BRIDGE_RUN_MODE === "dev";
-  const forceSourceBuild = env.CLAWDEX_BRIDGE_FORCE_SOURCE_BUILD === "true";
-
+function resolveLaunch(rootDir, env, { devMode, forceSourceBuild }) {
   if (devMode) {
     if (!commandExists("cargo")) {
       console.error("error: missing Rust/Cargo toolchain for dev bridge mode.");
       process.exit(1);
     }
 
-    spawnAndRelay("cargo", ["run"], {
+    return {
+      command: "cargo",
+      args: ["run"],
       cwd: path.join(rootDir, "services", "rust-bridge"),
       env,
-    });
-    return;
+      healthTimeoutMs: DEV_HEALTH_TIMEOUT_MS,
+    };
   }
 
   const overrideBinary = env.CLAWDEX_BRIDGE_BINARY ? path.resolve(env.CLAWDEX_BRIDGE_BINARY) : "";
@@ -196,22 +351,37 @@ function start() {
       process.exit(1);
     }
     ensureExecutable(overrideBinary);
-    spawnAndRelay(overrideBinary, [], { cwd: rootDir, env });
-    return;
+    return {
+      command: overrideBinary,
+      args: [],
+      cwd: rootDir,
+      env,
+      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+    };
   }
 
   const packagedBinary = packagedBinaryPath(rootDir, resolveRuntimeTarget());
   if (!forceSourceBuild && packagedBinary && fs.existsSync(packagedBinary)) {
     ensureExecutable(packagedBinary);
-    spawnAndRelay(packagedBinary, [], { cwd: rootDir, env });
-    return;
+    return {
+      command: packagedBinary,
+      args: [],
+      cwd: rootDir,
+      env,
+      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+    };
   }
 
   const builtBinary = builtBinaryPath(rootDir, os.platform());
   if (isBuiltBinaryFresh(rootDir, builtBinary)) {
     ensureExecutable(builtBinary);
-    spawnAndRelay(builtBinary, [], { cwd: rootDir, env });
-    return;
+    return {
+      command: builtBinary,
+      args: [],
+      cwd: rootDir,
+      env,
+      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+    };
   }
 
   if (!commandExists("cargo")) {
@@ -234,7 +404,44 @@ function start() {
   }
 
   ensureExecutable(builtBinary);
-  spawnAndRelay(builtBinary, [], { cwd: rootDir, env });
+  return {
+    command: builtBinary,
+    args: [],
+    cwd: rootDir,
+    env,
+    healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+  };
+}
+
+async function start() {
+  const rootDir = resolveRootDir();
+  const secureEnvFile = path.join(rootDir, ".env.secure");
+  if (!fs.existsSync(secureEnvFile)) {
+    console.error(`error: ${secureEnvFile} not found. Run: npm run secure:setup`);
+    process.exit(1);
+  }
+
+  const fileEnv = readEnvFile(secureEnvFile);
+  const env = { ...fileEnv, ...process.env };
+  const devMode = process.argv.includes("--dev") || env.BRIDGE_RUN_MODE === "dev";
+  const backgroundMode = process.argv.includes("--background");
+  const forceSourceBuild = env.CLAWDEX_BRIDGE_FORCE_SOURCE_BUILD === "true";
+  const launch = resolveLaunch(rootDir, env, { devMode, forceSourceBuild });
+
+  if (backgroundMode) {
+    await spawnDetachedAndWait(launch.command, launch.args, {
+      cwd: launch.cwd,
+      env: launch.env,
+      rootDir,
+      healthTimeoutMs: launch.healthTimeoutMs,
+    });
+    return;
+  }
+
+  spawnAndRelay(launch.command, launch.args, { cwd: launch.cwd, env: launch.env });
 }
 
-start();
+start().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/stop-services.sh

@@ -9,10 +9,68 @@ fi
 
 BRIDGE_PID_FILE="$ROOT_DIR/.bridge.pid"
 EXPO_PID_FILE="$ROOT_DIR/.expo.pid"
+SECURE_ENV_FILE="$ROOT_DIR/.env.secure"
 
 list_matching_pids() {
   local pattern="$1"
-  pgrep -f "$pattern" 2>/dev/null || true
+  ps -ax -o pid= -o command= 2>/dev/null | awk -v pattern="$pattern" '
+    $0 ~ pattern { print $1 }
+  ' || true
+}
+
+stop_pid_file_process() {
+  local label="$1"
+  local pid_file="$2"
+  local pid=""
+
+  if [[ ! -f "$pid_file" ]]; then
+    return 1
+  fi
+
+  pid="$(tr -dc '0-9' <"$pid_file")"
+  if [[ -z "$pid" ]]; then
+    rm -f "$pid_file"
+    return 1
+  fi
+
+  if ! kill -0 "$pid" 2>/dev/null; then
+    rm -f "$pid_file"
+    return 1
+  fi
+
+  echo "Stopping $label process from pid file: $pid"
+  kill -INT "$pid" 2>/dev/null || true
+  sleep 1
+
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -TERM "$pid" 2>/dev/null || true
+    sleep 1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -KILL "$pid" 2>/dev/null || true
+    echo "Force stopped $label process: $pid"
+  else
+    echo "$label stopped."
+  fi
+
+  rm -f "$pid_file"
+  return 0
+}
+
+extract_env_value() {
+  local file="$1"
+  local key="$2"
+  [[ -f "$file" ]] || return 1
+
+  awk -F= -v key="$key" '
+    $1 == key {
+      sub(/^[[:space:]]+/, "", $2)
+      sub(/[[:space:]]+$/, "", $2)
+      print $2
+      exit
+    }
+  ' "$file"
 }
 
 stop_process_group() {
@@ -54,8 +112,19 @@ stop_process_group() {
 echo "Stopping Clawdex services for project: $ROOT_DIR"
 
 stop_process_group "Expo" "$ROOT_DIR/.*/expo start|$ROOT_DIR/node_modules/.bin/expo start"
+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"
 
+if [[ -f "$SECURE_ENV_FILE" ]]; then
+  BRIDGE_ENABLED_ENGINES="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ENABLED_ENGINES" || true)"
+  BRIDGE_ACTIVE_ENGINE="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ACTIVE_ENGINE" || true)"
+  BRIDGE_OPENCODE_PORT="$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_OPENCODE_PORT" || true)"
+  BRIDGE_OPENCODE_PORT="${BRIDGE_OPENCODE_PORT:-4090}"
+  if [[ ",$BRIDGE_ENABLED_ENGINES,$BRIDGE_ACTIVE_ENGINE," == *",opencode,"* ]]; then
+    stop_process_group "OpenCode server" "opencode serve --hostname .* --port $BRIDGE_OPENCODE_PORT|\\.opencode serve --hostname .* --port $BRIDGE_OPENCODE_PORT"
+  fi
+fi
+
 rm -f "$BRIDGE_PID_FILE" "$EXPO_PID_FILE"
 echo "Done."

package/services/rust-bridge/Cargo.lock

@@ -149,12 +149,13 @@ dependencies = [
 
 [[package]]
 name = "codex-rust-bridge"
-version = "5.0.5-internal.9"
+version = "5.0.5"
 dependencies = [
  "axum",
  "base64",
  "chrono",
  "futures-util",
+ "libc",
  "qr2term",
  "reqwest",
  "serde",

package/services/rust-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-rust-bridge"
-version = "5.0.5-internal.9"
+version = "5.0.5"
 edition = "2021"
 
 [dependencies]
@@ -8,6 +8,7 @@ axum = { version = "0.8", features = ["ws", "http1", "tokio"] }
 base64 = "0.22"
 chrono = { version = "0.4", features = ["clock", "serde"] }
 futures-util = "0.3"
+libc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 shlex = "1"

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

@@ -338,6 +338,15 @@ impl RuntimeBackend {
         }))
     }
 
+    async fn shutdown(&self) {
+        if let Some(codex) = &self.codex {
+            codex.request_shutdown().await;
+        }
+        if let Some(opencode) = &self.opencode {
+            opencode.request_shutdown().await;
+        }
+    }
+
     fn engine(&self) -> BridgeRuntimeEngine {
         self.preferred_engine
     }
@@ -600,6 +609,95 @@ impl RuntimeBackend {
     }
 }
 
+fn configure_managed_child_command(command: &mut Command) {
+    command.kill_on_drop(true);
+    #[cfg(unix)]
+    command.process_group(0);
+}
+
+async fn terminate_managed_child(pid: u32, label: &str) {
+    #[cfg(unix)]
+    {
+        terminate_process_group_unix(pid, label).await;
+        return;
+    }
+
+    #[cfg(windows)]
+    {
+        terminate_process_tree_windows(pid, label).await;
+        return;
+    }
+
+    #[allow(unreachable_code)]
+    let _ = (pid, label);
+}
+
+#[cfg(unix)]
+async fn wait_for_shutdown_signal() -> &'static str {
+    let mut sigint = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
+        .expect("failed to install SIGINT handler");
+    let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+        .expect("failed to install SIGTERM handler");
+
+    tokio::select! {
+        _ = sigint.recv() => "SIGINT",
+        _ = sigterm.recv() => "SIGTERM",
+    }
+}
+
+#[cfg(not(unix))]
+async fn wait_for_shutdown_signal() -> &'static str {
+    let _ = tokio::signal::ctrl_c().await;
+    "Ctrl+C"
+}
+
+#[cfg(unix)]
+async fn terminate_process_group_unix(pid: u32, label: &str) {
+    let process_group = pid as i32;
+    if process_group <= 0 {
+        return;
+    }
+
+    let terminate_result = unsafe { libc::killpg(process_group, libc::SIGTERM) };
+    if terminate_result != 0 {
+        let error = std::io::Error::last_os_error();
+        if error.raw_os_error() != Some(libc::ESRCH) {
+            eprintln!("failed to terminate {label} process group {process_group}: {error}");
+        }
+        return;
+    }
+
+    tokio::time::sleep(Duration::from_millis(400)).await;
+
+    let kill_result = unsafe { libc::killpg(process_group, 0) };
+    if kill_result == 0 {
+        let force_result = unsafe { libc::killpg(process_group, libc::SIGKILL) };
+        if force_result != 0 {
+            let error = std::io::Error::last_os_error();
+            if error.raw_os_error() != Some(libc::ESRCH) {
+                eprintln!("failed to force-kill {label} process group {process_group}: {error}");
+            }
+        }
+    }
+}
+
+#[cfg(windows)]
+async fn terminate_process_tree_windows(pid: u32, label: &str) {
+    let status = Command::new("taskkill")
+        .arg("/PID")
+        .arg(pid.to_string())
+        .arg("/T")
+        .arg("/F")
+        .status()
+        .await;
+
+    match status {
+        Ok(result) if result.success() => {}
+        Ok(result) => eprintln!("failed to terminate {label} process tree {pid}: {result}"),
+        Err(error) => eprintln!("failed to terminate {label} process tree {pid}: {error}"),
+    }
+}
+
 enum RuntimeBackendRef<'a> {
     Codex(&'a Arc<AppServerBridge>),
     Opencode(&'a Arc<OpencodeBackend>),
@@ -773,6 +871,7 @@ impl ClientHub {
 struct AppServerBridge {
     engine: BridgeRuntimeEngine,
     child: Mutex<Child>,
+    child_pid: u32,
     writer: Mutex<ChildStdin>,
     pending_requests: Mutex<HashMap<u64, PendingRequest>>,
     internal_waiters: Mutex<HashMap<u64, oneshot::Sender<Result<Value, String>>>>,
@@ -815,15 +914,22 @@ impl AppServerBridge {
         engine: BridgeRuntimeEngine,
         hub: Arc<ClientHub>,
     ) -> Result<Arc<Self>, String> {
-        let mut child = Command::new(cli_bin)
+        let mut command = Command::new(cli_bin);
+        command
             .arg("app-server")
             .arg("--listen")
             .arg("stdio://")
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
+            .stderr(Stdio::piped());
+        configure_managed_child_command(&mut command);
+
+        let mut child = command
             .spawn()
             .map_err(|error| format!("failed to start app-server: {error}"))?;
+        let child_pid = child
+            .id()
+            .ok_or_else(|| "app-server pid unavailable".to_string())?;
 
         let stdin = child
             .stdin
@@ -841,6 +947,7 @@ impl AppServerBridge {
         let bridge = Arc::new(Self {
             engine,
             child: Mutex::new(child),
+            child_pid,
             writer: Mutex::new(stdin),
             pending_requests: Mutex::new(HashMap::new()),
             internal_waiters: Mutex::new(HashMap::new()),
@@ -861,6 +968,10 @@ impl AppServerBridge {
         Ok(bridge)
     }
 
+    async fn request_shutdown(&self) {
+        terminate_managed_child(self.child_pid, "app-server").await;
+    }
+
     async fn initialize(&self) -> Result<(), String> {
         let init_id = self.next_request_id.fetch_add(1, Ordering::Relaxed);
         let (tx, rx) = oneshot::channel::<Result<Value, String>>();
@@ -1519,6 +1630,7 @@ struct OpencodePendingUserInputEntry {
 
 struct OpencodeBackend {
     child: Mutex<Child>,
+    child_pid: u32,
     hub: Arc<ClientHub>,
     http: HttpClient,
     base_url: Url,
@@ -1547,6 +1659,7 @@ impl OpencodeBackend {
             .stdin(Stdio::null())
             .stdout(Stdio::piped())
             .stderr(Stdio::piped());
+        configure_managed_child_command(&mut command);
 
         if let Some(password) = config.opencode_server_password.as_deref() {
             command.env("OPENCODE_SERVER_PASSWORD", password);
@@ -1556,6 +1669,9 @@ impl OpencodeBackend {
         let mut child = command
             .spawn()
             .map_err(|error| format!("failed to start opencode serve: {error}"))?;
+        let child_pid = child
+            .id()
+            .ok_or_else(|| "opencode pid unavailable".to_string())?;
 
         let stdout = child
             .stdout
@@ -1574,6 +1690,7 @@ impl OpencodeBackend {
 
         let backend = Arc::new(Self {
             child: Mutex::new(child),
+            child_pid,
             hub,
             http: HttpClient::builder()
                 .build()
@@ -1600,6 +1717,10 @@ impl OpencodeBackend {
         Ok(backend)
     }
 
+    async fn request_shutdown(&self) {
+        terminate_managed_child(self.child_pid, "opencode").await;
+    }
+
     fn spawn_stdout_loop(self: &Arc<Self>, stdout: ChildStdout) {
         tokio::spawn(async move {
             let mut lines = BufReader::new(stdout).lines();
@@ -4126,7 +4247,7 @@ async fn main() {
         .route("/rpc", get(ws_handler))
         .route("/health", get(health_handler))
         .route("/local-image", get(local_image_handler))
-        .with_state(state);
+        .with_state(state.clone());
 
     let bind_addr = format!("{}:{}", config.host, config.port);
     let listener = match tokio::net::TcpListener::bind(&bind_addr).await {
@@ -4140,7 +4261,18 @@ async fn main() {
     println!("rust-bridge listening on {bind_addr}");
     maybe_print_pairing_qr(&config);
 
-    if let Err(error) = axum::serve(listener, app).await {
+    let shutdown_backend = state.backend.clone();
+    let serve_result = axum::serve(listener, app)
+        .with_graceful_shutdown(async move {
+            let signal = wait_for_shutdown_signal().await;
+            eprintln!("shutdown signal received ({signal}), terminating managed backends");
+            shutdown_backend.shutdown().await;
+        })
+        .await;
+
+    state.backend.shutdown().await;
+
+    if let Err(error) = serve_result {
         eprintln!("server error: {error}");
         std::process::exit(1);
     }
@@ -7373,6 +7505,7 @@ mod tests {
         Arc::new(AppServerBridge {
             engine: BridgeRuntimeEngine::Codex,
             child: Mutex::new(child),
+            child_pid: 0,
             writer: Mutex::new(writer),
             pending_requests: Mutex::new(HashMap::new()),
             internal_waiters: Mutex::new(HashMap::new()),
@@ -7401,6 +7534,7 @@ mod tests {
 
         Arc::new(OpencodeBackend {
             child: Mutex::new(child),
+            child_pid: 0,
             hub,
             http: HttpClient::builder().build().expect("build reqwest client"),
             base_url: Url::parse("http://127.0.0.1:4090/").expect("valid opencode base url"),
@@ -8999,6 +9133,7 @@ mod tests {
         let bridge = Arc::new(AppServerBridge {
             engine: BridgeRuntimeEngine::Codex,
             child: Mutex::new(child),
+            child_pid: 0,
             writer: Mutex::new(writer),
             pending_requests: Mutex::new(HashMap::new()),
             internal_waiters: Mutex::new(HashMap::new()),