run.sh

#!/bin/bash
# Better Agent — prod-mode launcher.
#
# Backend runs WITHOUT uvicorn --reload (no code hot-reload).
# Frontend is served as built static files from the backend port
# (no Vite dev server, no HMR).
#
# To pick up frontend OR backend code changes from a browser, the user
# clicks the "Refresh" button in the UI — it POSTs /api/admin/restart,
# which sets a flag file and SIGTERMs uvicorn. The loop below detects
# the flag, starts the new backend, then rebuilds the frontend while the
# backend serves the previous build. The page reloads after the atomic
# frontend swap completes.
#
# Ctrl+C terminates the loop (uvicorn exits without the flag set).
#
# The restart flag lives at ba_home()/restart_requested — same path the
# backend writes via `paths.ba_home()`.
#
# Auth credentials (username + argon2 hash + session secret) live in
# the macOS login keychain under service "better-agent", with legacy
# "better-claude" entries still read and reset.

set -e
set -o pipefail

DIR="$(cd "$(dirname "$0")" && pwd)"
BA_HOME="${BETTER_AGENT_HOME:-${BETTER_CLAUDE_HOME:-$HOME/.better-claude}}"

case "${1:-}" in
  --install-service|--uninstall-service|--service-status)
    case "$1" in
      --install-service) SERVICE_ACTION=install ;;
      --uninstall-service) SERVICE_ACTION=uninstall ;;
      --service-status) SERVICE_ACTION=status ;;
    esac
    exec python3 "$DIR/scripts/run_service.py" "$SERVICE_ACTION" --checkout "$DIR" --home "$BA_HOME"
    ;;
  --service-child)
    export BETTER_AGENT_RUN_SH_SERVICE_CHILD=1
    shift
    ;;
esac

bas_available() {
  if [ "${BETTER_AGENT_RUN_SH_ASSUME_NO_BAS:-0}" = "1" ]; then
    return 1
  fi
  command -v bas >/dev/null 2>&1 || [ -x "$HOME/ba-switch/bas" ]
}

bas_executable() {
  if command -v bas >/dev/null 2>&1; then
    command -v bas
    return
  fi
  if [ -x "$HOME/ba-switch/bas" ]; then
    printf '%s\n' "$HOME/ba-switch/bas"
    return
  fi
  return 1
}

current_checkout_is_main_line() {
  case "$(basename "$DIR")" in
    *-main)
      return 0
      ;;
  esac
  if command -v git >/dev/null 2>&1; then
    local branch
    branch="$(git -C "$DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
    [ "$branch" = "main" ] || [ "$branch" = "master" ]
    return
  fi
  return 1
}

main_checkout_for_current_line() {
  local name parent candidate
  name="$(basename "$DIR")"
  parent="$(dirname "$DIR")"
  case "$name" in
    *-qa)
      candidate="$parent/${name%-qa}-main"
      ;;
    *)
      candidate="$DIR-main"
      ;;
  esac
  if [ -x "$candidate/run.sh" ]; then
    printf '%s\n' "$candidate"
    return 0
  fi
  return 1
}

if [ "${BETTER_AGENT_RUN_SH_SERVICE_CHILD:-0}" != "1" ]; then
  BAS_BIN="$(bas_executable || true)"
  if [ -n "$BAS_BIN" ]; then
    BAS_LINE="$("$BAS_BIN" resolve-line "$DIR" 2>/dev/null || true)"
    if [[ "$BAS_LINE" =~ ^[a-z0-9][a-z0-9_.-]{0,31}$ ]]; then
      echo "BAS owns this checkout as line $BAS_LINE; delegating startup"
      exec "$BAS_BIN" exec-line "$BAS_LINE"
    fi
  fi
fi

if [ "${BETTER_AGENT_RUN_SH_SERVICE_CHILD:-0}" != "1" ] && ! bas_available && ! current_checkout_is_main_line; then
  MAIN_CHECKOUT="$(main_checkout_for_current_line || true)"
  if [ -n "$MAIN_CHECKOUT" ]; then
    echo "bas is not installed; launching main checkout at $MAIN_CHECKOUT"
    exec "$MAIN_CHECKOUT/run.sh" "$@"
  fi
  echo "bas is not installed and no sibling main checkout is available; launching current checkout at $DIR"
fi

export BETTER_AGENT_HOME="${BETTER_AGENT_HOME:-$BA_HOME}"
export BETTER_CLAUDE_HOME="${BETTER_CLAUDE_HOME:-$BA_HOME}"
FLAG="$BA_HOME/restart_requested"
RESULT="$BA_HOME/refresh_result.json"
BACKEND_LOG="$BA_HOME/backend-run.log"
KC_SVC="better-agent"
KC_LEGACY_SVC="better-claude"
export PATH="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:$PATH"
PY=""
CREDENTIAL_AUTHORITY="$DIR/desktop/dist/BetterAgentCredentialAuthority/BetterAgentCredentialAuthority"
DEFAULT_BACKEND_PORT=18765
BACKEND_PORT="${BETTER_AGENT_BACKEND_PORT:-${BETTER_CLAUDE_BACKEND_PORT:-$DEFAULT_BACKEND_PORT}}"
GRACEFUL_RESTART_TIMEOUT_SECONDS="${BETTER_AGENT_GRACEFUL_RESTART_TIMEOUT_SECONDS:-8}"
if ! [[ "$GRACEFUL_RESTART_TIMEOUT_SECONDS" =~ ^[0-9]+$ ]] || [ "$GRACEFUL_RESTART_TIMEOUT_SECONDS" -lt 1 ]; then
  GRACEFUL_RESTART_TIMEOUT_SECONDS=8
fi
# The venv is created by `uv`, which does not install `pip` into it. Drive
# dependency installs through `uv pip` against the venv's interpreter.
UV="$(command -v uv || echo "$HOME/.local/bin/uv")"

mkdir -p "$BA_HOME"

# Default topology path to $BA_HOME/topology.yaml when unset, so the
# multi-machine `nodes` infrastructure (node_store, /api/nodes,
# RemoteProviderProxy) loads if the file is present. Backend tolerates
# the file being absent — it just logs the load failure and runs in
# single-machine mode. Explicit env var overrides the default.
TOPOLOGY_PATH="${BETTER_AGENT_TOPOLOGY_PATH:-${BETTER_CLAUDE_TOPOLOGY_PATH:-$BA_HOME/topology.yaml}}"
export BETTER_AGENT_TOPOLOGY_PATH="$TOPOLOGY_PATH"
export BETTER_CLAUDE_TOPOLOGY_PATH="$TOPOLOGY_PATH"
# Lets /api/admin/restart reject unsafe self-termination when uvicorn was
# launched directly and no outer process exists to rebuild and respawn it.
export BETTER_AGENT_RUN_SH_SUPERVISOR=1
export BETTER_CLAUDE_RUN_SH_SUPERVISOR=1

# --- Keychain helpers ------------------------------------------------
# All calls shell out to /usr/bin/security so the ACL on every stored
# entry is owned by `security` itself — no GUI permission prompt when
# the backend later reads them. See backend/auth_secrets.py for the
# matching invariant.
kc_has() {
  # Check existence only. Do NOT use `-g`: `-g` attempts to READ the
  # stored password, which on some macOS versions returns non-zero
  # when the binary doesn't have read-ACL access yet (chicken-and-
  # egg on the very first read after add-generic-password). Without
  # `-g` we just probe attributes — always permitted, no GUI prompt.
  /usr/bin/security find-generic-password -s "$KC_SVC" -a "$1" >/dev/null 2>&1 \
    || /usr/bin/security find-generic-password -s "$KC_LEGACY_SVC" -a "$1" >/dev/null 2>&1
}
kc_set() {
  /usr/bin/security add-generic-password -U -s "$KC_SVC" -a "$1" -w "$2"
  /usr/bin/security add-generic-password -U -s "$KC_LEGACY_SVC" -a "$1" -w "$2"
}
kc_del() {
  /usr/bin/security delete-generic-password -s "$KC_SVC" -a "$1" >/dev/null 2>&1 || true
  /usr/bin/security delete-generic-password -s "$KC_LEGACY_SVC" -a "$1" >/dev/null 2>&1 || true
}

# --- --reset-auth ----------------------------------------------------
if [ "${1:-}" = "--reset-auth" ]; then
  echo "This will WIPE the stored Better Agent credentials from the"
  echo "macOS keychain (username, password hash, session secret)."
  read -p "Type 'yes' to confirm: " ans
  if [ "$ans" != "yes" ]; then
    echo "Aborted."
    exit 1
  fi
  kc_del username
  kc_del password_hash
  kc_del session_secret
  rm -f "$BA_HOME/qr_auth_state.json"
  echo "Wiped. Run ./run.sh to bootstrap new credentials."
  exit 0
fi

bootstrap_hint() {
  if [ "$(uname -s)" = "Darwin" ]; then
    echo "Run ./scripts/install-macos.sh, then run ./run.sh again." >&2
    return 0
  fi
  echo "Install the missing prerequisites listed above, then run ./run.sh again." >&2
}

ensure_base_prereqs() {
  local missing=""
  local cmd=""

  for cmd in git npm node curl; do
    if ! command -v "$cmd" >/dev/null 2>&1; then
      missing="${missing}${missing:+ }$cmd"
    fi
  done
  if [ ! -x "$UV" ]; then
    missing="${missing}${missing:+ }uv"
  fi

  if [ -z "$missing" ]; then
    return 0
  fi

  echo "Missing required startup tool(s): $missing" >&2
  bootstrap_hint
  exit 1
}

kill_port_listeners() {
  local port="$1"
  local pids=""
  local attempts=0

  if ! command -v lsof >/dev/null 2>&1; then
    echo "Cannot kill listeners on :$port because lsof is not installed." >&2
    return 1
  fi

  stop_known_better_agent_port_users "$port"

  pids="$(lsof -tiTCP:"$port" -sTCP:LISTEN 2>/dev/null | sort -u || true)"
  if [ -n "$pids" ]; then
    echo "$pids" | xargs kill -15 2>/dev/null || true
  fi

  while [ "$attempts" -lt 20 ]; do
    pids="$(lsof -tiTCP:"$port" -sTCP:LISTEN 2>/dev/null | sort -u || true)"
    if [ -z "$pids" ]; then
      return 0
    fi
    attempts=$((attempts + 1))
    sleep 0.25
  done

  if [ -n "$pids" ]; then
    echo "Force killing remaining PIDs on :$port..."
    echo "$pids" | xargs kill -9 2>/dev/null || true
  fi
  sleep 0.5
  pids="$(lsof -tiTCP:"$port" -sTCP:LISTEN 2>/dev/null | sort -u || true)"
  if [ -n "$pids" ]; then
    echo "Port :$port is still occupied by listener PID(s):"
    lsof -nP -iTCP:"$port" -sTCP:LISTEN || true
    return 1
  fi
  return 0
}

port_in_use() {
  local port="$1"
  if command -v lsof >/dev/null 2>&1; then
    lsof -tiTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1
    return $?
  fi
  (echo >"/dev/tcp/127.0.0.1/$port") >/dev/null 2>&1
}

resolve_port_conflict() {
  local port="$1"
  local label="$2"
  local answer=""
  local new_port=""

  while true; do
    if ! port_in_use "$port"; then
      echo "$port"
      return 0
    fi
    echo >&2
    if command -v lsof >/dev/null 2>&1; then
      echo "$label port :$port is already in use by:" >&2
      lsof -nP -iTCP:"$port" -sTCP:LISTEN >&2 || true
    else
      echo "$label port :$port is already in use; listener details are unavailable because lsof is not installed." >&2
    fi
    echo >&2
    if command -v lsof >/dev/null 2>&1; then
      read -r -p "Kill those process(es), use a different port, or abort? [k/p/a]: " answer >&2
    else
      read -r -p "Use a different port or abort? [p/a]: " answer >&2
    fi
    case "$answer" in
      k|K)
        if ! command -v lsof >/dev/null 2>&1; then
          echo "Kill requires lsof. Choose p or a." >&2
          continue
        fi
        kill_port_listeners "$port" || return 1
        ;;
      p|P)
        read -r -p "New $label port: " new_port >&2
        if ! [[ "$new_port" =~ ^[0-9]+$ ]] || [ "$new_port" -lt 1 ] || [ "$new_port" -gt 65535 ]; then
          echo "Port must be a number between 1 and 65535." >&2
          continue
        fi
        port="$new_port"
        ;;
      a|A)
        return 1
        ;;
      *)
        if command -v lsof >/dev/null 2>&1; then
          echo "Choose k, p, or a." >&2
        else
          echo "Choose p or a." >&2
        fi
        ;;
    esac
  done
}

bootout_launchctl_job() {
  local label="$1"
  local domain="gui/$(id -u)"

  if launchctl print "$domain/$label" >/dev/null 2>&1; then
    echo "Stopping launchctl job $label..."
    launchctl bootout "$domain/$label" >/dev/null 2>&1 || true
  fi
}

kill_matching_processes() {
  local label="$1"
  local pattern="$2"
  local pids=""
  local attempts=0
  local pid=""

  for pid in $(pgrep -f "$pattern" 2>/dev/null || true); do
    if [ "$pid" != "$$" ]; then
      pids="${pids}${pids:+ }$pid"
    fi
  done
  if [ -z "$pids" ]; then
    return 0
  fi

  echo "Stopping previous $label process(es): $pids"
  echo "$pids" | xargs kill -15 2>/dev/null || true

  while [ "$attempts" -lt 20 ]; do
    pids=""
    for pid in $(pgrep -f "$pattern" 2>/dev/null || true); do
      if [ "$pid" != "$$" ]; then
        pids="${pids}${pids:+ }$pid"
      fi
    done
    if [ -z "$pids" ]; then
      return 0
    fi
    attempts=$((attempts + 1))
    sleep 0.25
  done

  echo "Force killing previous $label process(es): $pids"
  echo "$pids" | xargs kill -9 2>/dev/null || true
}

process_is_running() {
  local pid="$1"
  local stat=""

  if ! kill -0 "$pid" 2>/dev/null; then
    return 1
  fi
  stat="$(ps -p "$pid" -o stat= 2>/dev/null || true)"
  case "$stat" in
    *Z*) return 1 ;;
    *) return 0 ;;
  esac
}

FRONTEND_BUILD_PID=""
BACKEND_PID=""
BACKEND_GENERATION_ID=""
BACKEND_GENERATION_STARTED_AT=""
BACKEND_EXIT_CODE=0
BACKEND_EXIT_PID=""
ZAI_STARTUP_CHECK_PID=""
DAEMON_HOST_PID=""
CREDENTIAL_BACKEND_SUPERVISOR_PID=""
CREDENTIAL_BACKEND_CONTROL_DIR=""
CREDENTIAL_BACKEND_CONTROL=""

tracked_child_is_running() {
  local pid="$1"
  local ppid=""

  if [ -z "$pid" ] || ! process_is_running "$pid"; then
    return 1
  fi
  ppid="$(ps -p "$pid" -o ppid= 2>/dev/null | tr -d ' ' || true)"
  [ "$ppid" = "$$" ]
}

collect_descendants() {
  local pid="$1"
  local child=""

  for child in $(pgrep -P "$pid" 2>/dev/null || true); do
    collect_descendants "$child"
    echo "$child"
  done
}

reap_completed_children() {
  if [ -n "$FRONTEND_BUILD_PID" ] && ! tracked_child_is_running "$FRONTEND_BUILD_PID"; then
    FRONTEND_BUILD_PID=""
  fi
  if [ -n "$ZAI_STARTUP_CHECK_PID" ] && ! tracked_child_is_running "$ZAI_STARTUP_CHECK_PID"; then
    ZAI_STARTUP_CHECK_PID=""
  fi
}

stop_child_process() {
  local label="$1"
  local pid="$2"
  local attempts=0
  local pids=""

  if ! tracked_child_is_running "$pid"; then
    return 0
  fi

  echo "Stopping $label (PID $pid)..."
  pids="$(collect_descendants "$pid"; echo "$pid")"
  echo "$pids" | xargs kill -15 2>/dev/null || true
  while [ "$attempts" -lt 20 ]; do
    pids="$(echo "$pids" | while read -r child_pid; do
      if [ -n "$child_pid" ] && process_is_running "$child_pid"; then
        echo "$child_pid"
      fi
    done)"
    if [ -z "$pids" ]; then
      return 0
    fi
    attempts=$((attempts + 1))
    sleep 0.25
  done
  echo "Force killing $label (PID $pid)..."
  echo "$pids" | xargs kill -9 2>/dev/null || true
}

credential_backend_control() {
  PYTHONPATH="$DIR:$DIR/backend:$DIR/desktop:$DIR/sdk" "$PY" \
    -m desktop.browser_backend_control --control "$CREDENTIAL_BACKEND_CONTROL" "$@"
}

STATUS_TERMINAL=""
STATUS_PID=""
STATUS_GENERATION_ID=""
STATUS_RETURNCODE=""
STATUS_STARTED_AT=""

read_backend_status() {
  local status_file="$CREDENTIAL_BACKEND_CONTROL_DIR/status.json"
  local parsed=""
  if ! credential_backend_control status > "$status_file"; then
    rm -f "$status_file"
    return 1
  fi
  if ! parsed="$("$PY" - "$status_file" <<'PY'
import json, sys
with open(sys.argv[1], encoding="utf-8") as handle:
    status = json.load(handle)
fields = (
    "1" if status.get("terminal") is True else "0",
    str(status.get("pid") if isinstance(status.get("pid"), int) else "-"),
    str(status.get("generation_id") or "-"),
    str(status.get("returncode") if isinstance(status.get("returncode"), int) else "-"),
    str(status.get("started_at") if isinstance(status.get("started_at"), (int, float)) else "-"),
)
print("|".join(fields))
PY
)"; then
    rm -f "$status_file"
    return 1
  fi
  rm -f "$status_file"
  IFS='|' read -r STATUS_TERMINAL STATUS_PID STATUS_GENERATION_ID \
    STATUS_RETURNCODE STATUS_STARTED_AT <<EOF
$parsed
EOF
}

start_credential_backend_supervisor() {
  local attempts=0
  CREDENTIAL_BACKEND_CONTROL_DIR="$(mktemp -d "/tmp/ba-bs.XXXXXX")"
  chmod 700 "$CREDENTIAL_BACKEND_CONTROL_DIR"
  CREDENTIAL_BACKEND_CONTROL="$CREDENTIAL_BACKEND_CONTROL_DIR/control.sock"
  if [ "$(uname -s)" = "Darwin" ]; then
    "$DIR/desktop/build_credential_authority.sh" >/dev/null
    "$CREDENTIAL_AUTHORITY" \
      --control "$CREDENTIAL_BACKEND_CONTROL" \
      --launcher-root "$DIR" \
      --controller-pid "$$" &
  else
    PYTHONPATH="$DIR:$DIR/backend:$DIR/desktop:$DIR/sdk" "$PY" \
      -m desktop.browser_backend_supervisor \
      --control "$CREDENTIAL_BACKEND_CONTROL" \
      --launcher-root "$DIR" \
      --controller-pid "$$" &
  fi
  CREDENTIAL_BACKEND_SUPERVISOR_PID=$!
  while [ ! -S "$CREDENTIAL_BACKEND_CONTROL" ]; do
    if ! tracked_child_is_running "$CREDENTIAL_BACKEND_SUPERVISOR_PID"; then
      echo "Credential backend supervisor failed to start." >&2
      return 1
    fi
    if [ "$attempts" -ge 40 ]; then
      echo "Credential backend supervisor startup timed out." >&2
      return 1
    fi
    attempts=$((attempts + 1))
    sleep 0.05
  done
}

stop_credential_backend_supervisor() {
  if [ -n "$CREDENTIAL_BACKEND_CONTROL" ] && [ -S "$CREDENTIAL_BACKEND_CONTROL" ]; then
    credential_backend_control shutdown >/dev/null 2>&1 || true
  fi
  stop_child_process "credential backend supervisor" "$CREDENTIAL_BACKEND_SUPERVISOR_PID"
  [ -n "$CREDENTIAL_BACKEND_CONTROL" ] && rm -f "$CREDENTIAL_BACKEND_CONTROL"
  [ -n "$CREDENTIAL_BACKEND_CONTROL_DIR" ] && rmdir "$CREDENTIAL_BACKEND_CONTROL_DIR" 2>/dev/null || true
  CREDENTIAL_BACKEND_SUPERVISOR_PID=""
  CREDENTIAL_BACKEND_CONTROL=""
  CREDENTIAL_BACKEND_CONTROL_DIR=""
}

shutdown_children() {
  local signal="${1:-TERM}"
  local exit_code=143

  trap - INT TERM
  if [ "$signal" = "INT" ]; then
    exit_code=130
  fi

  echo
  echo "Stopping Better Agent..."
  reap_completed_children
  stop_child_process "startup checker" "$ZAI_STARTUP_CHECK_PID"
  stop_child_process "frontend build" "$FRONTEND_BUILD_PID"
  stop_child_process "daemon host" "$DAEMON_HOST_PID"
  if [ -n "$CREDENTIAL_BACKEND_SUPERVISOR_PID" ]; then
    stop_credential_backend_supervisor
  else
    stop_child_process "backend" "$BACKEND_PID"
  fi
  exit "$exit_code"
}

trap 'shutdown_children INT' INT
trap 'shutdown_children TERM' TERM

if [ "${BETTER_AGENT_RUN_SH_TEST_SIGNAL_CLEANUP:-0}" = "1" ]; then
  ((sleep 30 & wait) & wait) &
  BACKEND_PID=$!
  (sleep 30 & wait) &
  FRONTEND_BUILD_PID=$!
  (sleep 30 & wait) >/dev/null 2>&1 &
  ZAI_STARTUP_CHECK_PID=$!
  echo "Signal cleanup test ready: backend=$BACKEND_PID frontend=$FRONTEND_BUILD_PID checker=$ZAI_STARTUP_CHECK_PID"
  while true; do
    sleep 1
  done
fi

kill_backend_lock_holder() {
  local lock_path="$BA_HOME/backend.lock"
  local pid=""
  local cmd=""
  local ppid=""
  local cwd=""
  local foreign_checkout=""
  local attempts=0

  if [ ! -f "$lock_path" ]; then
    return 0
  fi
  pid="$(sed -n 's/^pid=//p' "$lock_path" | head -n 1)"
  if ! [[ "$pid" =~ ^[0-9]+$ ]] || ! process_is_running "$pid"; then
    return 0
  fi

  cmd="$(ps -p "$pid" -o command= 2>/dev/null || true)"
  cwd="$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -n1 || true)"
  looks_like_ours=0
  case "$cmd" in
    *"$DIR/backend"*uvicorn*"main:app"*|*"$DIR/backend/app_entry.py"*"--serve"*)
      looks_like_ours=1
      ;;
    *uvicorn*"main:app"*)
      # The launcher runs `(cd "$DIR/backend" && source .venv/bin/activate &&
      # exec uvicorn main:app ...)`, so argv shows a relative
      # `.venv/bin/uvicorn` without the absolute checkout path. Accept it when
      # the process cwd is this checkout's backend dir. Also accept a sibling
      # checkout: backend.lock is keyed on BA_HOME (the shared state home),
      # not on the checkout directory, so a previous backend launched from
      # another worktree can legitimately hold the lock and must be replaced
      # here -- otherwise this relaunch can never win the lock and crashes.
      looks_like_ours=1
      if [ -n "$cwd" ] && [ "$cwd" != "$DIR/backend" ]; then
        foreign_checkout="$cwd"
      fi
      ;;
  esac
  if [ "$looks_like_ours" -ne 1 ]; then
    echo "Backend lock is held by PID $pid, but it does not look like this checkout's backend:"
    echo "$cmd"
    return 0
  fi

  if [ -n "$foreign_checkout" ]; then
    echo "Stopping previous Better Agent backend lock holder from a sibling checkout ($foreign_checkout): $pid"
  else
    echo "Stopping previous Better Agent backend lock holder: $pid"
  fi

  # Escalate TERM -> KILL and VERIFY death each round instead of a single
  # best-effort SIGTERM+SIGKILL fire-and-forget. A lock holder that survived
  # one round previously left the lock held indefinitely: the caller had no
  # idea the kill failed, so it proceeded straight into a doomed backend
  # start (fails the Python-side 15s lock retry) which burns a full,
  # expensive startup-checker AI-agent cycle just to hit the same wall
  # again on the next `run.sh` invocation.
  local round=0
  while [ "$round" -lt 3 ]; do
    round=$((round + 1))
    if [ "$round" -eq 1 ]; then
      kill -15 "$pid" 2>/dev/null || true
    else
      echo "Lock holder $pid still alive after round $((round - 1)); escalating to SIGKILL (round $round)..."
      kill -9 "$pid" 2>/dev/null || true
    fi
    attempts=0
    while [ "$attempts" -lt 20 ]; do
      if ! process_is_running "$pid"; then
        ppid="$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ' || true)"
        if [ -n "$ppid" ] && [ "$ppid" != "1" ]; then
          kill -15 "$ppid" 2>/dev/null || true
        fi
        echo "Lock holder $pid stopped (round $round)."
        return 0
      fi
      attempts=$((attempts + 1))
      sleep 0.25
    done
  done

  echo "FATAL: backend lock holder $pid ($cmd) would not die after repeated SIGTERM/SIGKILL — refusing to start a new backend against a lock we cannot free." >&2
  exit 1
}

stop_known_better_agent_port_users() {
  local port="$1"
  if [ "$port" != "$BACKEND_PORT" ]; then
    return 0
  fi
  bootout_launchctl_job "better-claude"
  kill_matching_processes \
    "Better Agent backend wrapper" \
    "cd $DIR/backend && .*uvicorn main:app.*--port $port"
  kill_matching_processes \
    "Better Agent backend" \
    "$DIR/backend.*uvicorn main:app.*--port $port"
}

ensure_base_prereqs

echo "Checking startup ports..."
kill_backend_lock_holder
BACKEND_PORT="$(resolve_port_conflict "$BACKEND_PORT" "backend")"
export BETTER_CLAUDE_BACKEND_PORT="$BACKEND_PORT"
export BETTER_CLAUDE_BACKEND_URL="http://127.0.0.1:$BACKEND_PORT"
export BETTER_AGENT_BACKEND_PORT="$BACKEND_PORT"
export BETTER_AGENT_BACKEND_URL="http://127.0.0.1:$BACKEND_PORT"
export BA_BACKEND_PORT="$BACKEND_PORT"

npm_project_hash() {
  local project_dir="$1"
  shift
  (cd "$project_dir" && node - "$@" <<'NODE'
const { createHash } = require("node:crypto");
const { readFileSync } = require("node:fs");

const outer = createHash("sha256");
for (const path of process.argv.slice(2)) {
  const inner = createHash("sha256").update(readFileSync(path)).digest("hex");
  outer.update(`${inner}  ${path}\n`);
}
process.stdout.write(outer.digest("hex"));
NODE
  )
}

sync_npm_project_deps() {
  local project_dir="$1"
  local label="$2"
  local install_mode="$3"
  local dependency_files=(package.json package-lock.json)
  local lock_file="package-lock.json"
  local stamp="$project_dir/node_modules/.better-agent-deps.stamp"
  local current=""
  local stamped=""

  if [ "$install_mode" = "mobile" ]; then
    dependency_files=(package.json mobile-dependencies.json package-lock.mobile.json)
    lock_file="package-lock.mobile.json"
  fi
  if [ ! -f "$project_dir/$lock_file" ]; then
    echo "$label dependency lock is missing; cannot install reproducibly." >&2
    exit 1
  fi

  current="$(npm_project_hash "$project_dir" "${dependency_files[@]}"):$install_mode"
  if [ -f "$stamp" ]; then
    stamped="$(cat "$stamp" 2>/dev/null || true)"
  fi
  if [ -d "$project_dir/node_modules" ] && [ "$stamped" = "$current" ]; then
    echo "$label npm deps unchanged — skipping install."
    return 0
  fi

  echo "Installing $label npm deps..."
  if [ "$install_mode" = "mobile" ]; then
    (cd "$project_dir" && npm run install:mobile-deps)
  elif [ "$install_mode" = "desktop" ]; then
    (cd "$project_dir" && npm run install:desktop-deps)
  else
    (cd "$project_dir" && npm ci)
  fi
  printf '%s' "$current" > "$stamp"
}

BOOTSTRAP_PYTHON="$(command -v python3 || command -v python || true)"
if [ -z "$BOOTSTRAP_PYTHON" ]; then
  echo "Python is required to resolve installation dependencies." >&2
  exit 1
fi

# A state home with no installation profile has nothing to serve. Adopt an
# already-installed provider CLI so a fresh home boots usable; never install a
# CLI here — that stays an explicit `scripts/install.py` run.
if ! PYTHONPATH="$DIR/backend" "$BOOTSTRAP_PYTHON" -c \
  'import installation_profile; raise SystemExit(0 if installation_profile.load()["status"] == "active" else 1)'; then
  ADOPT_PROVIDER="$(PYTHONPATH="$DIR/backend" "$BOOTSTRAP_PYTHON" -c \
    'import installation_bootstrap; print(installation_bootstrap.adoptable_provider_kind() or "")')"
  if [ -n "$ADOPT_PROVIDER" ]; then
    ADOPT_MODE="${BETTER_AGENT_INSTALL_MODE:-default}"
    echo "No installation profile in this state home — adopting installed provider '$ADOPT_PROVIDER' with mode '$ADOPT_MODE'."
    "$BOOTSTRAP_PYTHON" "$DIR/scripts/install.py" \
      --mode "$ADOPT_MODE" --provider "$ADOPT_PROVIDER" --yes --adopt \
      || echo "Installation profile adoption failed; finish setup from the app." >&2
  else
    echo "No installation profile and no provider CLI found — finish setup from the app." >&2
  fi
fi

# Provisioning follows the capability the user asked for, not what this
# bootstrap interpreter happens to have importable.
if PYTHONPATH="$DIR/backend" "$BOOTSTRAP_PYTHON" -c \
  'import installation_profile as p; raise SystemExit(0 if p.capability_requested(p.MOBILE) else 1)'; then
  FRONTEND_NPM_MODE="mobile"
else
  FRONTEND_NPM_MODE="desktop"
fi
sync_npm_project_deps "$DIR/frontend" "frontend" "$FRONTEND_NPM_MODE"

# --- Sync backend dependencies before anything that imports them ----
# Idempotent; cheap when deps are cached. Required so the argon2 import
# in the keychain-bootstrap block below works on a fresh checkout.
sync_backend_deps() {
  local bootstrap_python=""
  local active_env=""
  bootstrap_python="$BOOTSTRAP_PYTHON"
  if [ -z "$bootstrap_python" ]; then
    echo "Python is required to resolve backend dependencies." >&2
    exit 1
  fi
  echo "Activating backend dependency plan..."
  active_env="$("$bootstrap_python" "$DIR/backend/dependency_plan.py" activate --uv "$UV")"
  if [ "$(uname -s)" = "MINGW64_NT" ] || [ "$(uname -s)" = "MSYS_NT" ]; then
    PY="$active_env/Scripts/python.exe"
  else
    PY="$active_env/bin/python"
  fi
  if [ ! -x "$PY" ]; then
    echo "Activated backend environment is not runnable." >&2
    exit 1
  fi
  export BETTER_AGENT_BACKEND_PYTHON="$PY"
}
sync_backend_deps

# --- Install the `bagent` CLI command onto PATH (idempotent) --------
# Other tools (e.g. TestApe locator healing) shell out to `bagent`.
bash "$DIR/scripts/install-bagent.sh" || echo "bagent install failed (non-fatal)"

# --- First-time keychain bootstrap ----------------------------------
# A cleartext password is NEVER echoed (terminal scrollback, tmux/CI logs
# would leak a full-access credential). Three modes, none of which print a
# secret:
#   - BA_PASSWORD set    → use it silently (headless / scripted).
#   - interactive TTY    → prompt the operator to choose one.
#   - no TTY and no env  → mint a random one, do NOT print it; onboard via
#                          the login-screen QR, or `--reset-auth` to set a
#                          known password.
# Override the username via BA_USERNAME (defaults to a random ba-XXXX).
FIRST_RUN_AUTH_BOOTSTRAPPED=0
FIRST_RUN_BROWSER_OPENED=0
if [ "$(uname -s)" = "Darwin" ] && { ! kc_has username || ! kc_has password_hash || ! kc_has session_secret; }; then
  FIRST_RUN_AUTH_BOOTSTRAPPED=1
  echo
  echo "Better Agent — first-time auth setup (credentials live in your OS keychain only)."
  UNAME="${BA_USERNAME:-$("$PY" -c "import secrets; print('ba-'+secrets.token_hex(4))")}"
  PW=""
  if [ -n "${BA_PASSWORD:-}" ]; then
    PW="$BA_PASSWORD"
    echo "Using credentials from BA_USERNAME / BA_PASSWORD."
  elif [ -t 0 ]; then
    read -p "Username [$UNAME]: " _u; [ -n "$_u" ] && UNAME="$_u"
    while true; do
      read -s -p "Password: " PW1; echo
      read -s -p "Confirm:  " PW2; echo
      if [ -z "$PW1" ]; then echo "Empty password — try again."; continue; fi
      if [ "$PW1" != "$PW2" ]; then echo "Mismatch — try again."; continue; fi
      PW="$PW1"; break
    done
  else
    PW="$("$PY" -c "import secrets; print(secrets.token_urlsafe(18))")"
    echo "No TTY and no BA_PASSWORD — set a RANDOM password (not shown)."
    echo "Onboard devices via the QR on the login screen, or run ./run.sh --reset-auth to choose one."
  fi
  # Password reaches python via stdin (NOT argv) so it stays out of `ps`.
  HASH=$(printf '%s' "$PW" | "$PY" -c "import sys, argon2; print(argon2.PasswordHasher().hash(sys.stdin.read()))")
  SECRET=$("$PY" -c "import secrets; print(secrets.token_hex(32))")
  kc_set username "$UNAME"
  kc_set password_hash "$HASH"
  kc_set session_secret "$SECRET"
  unset PW PW1 PW2 _u HASH SECRET
  echo
  echo "Stored for user '$UNAME'. Starting backend..."
  echo
  unset UNAME
fi

rm -f "$FLAG"

build_frontend() {
  local request_id="${1:-}"
  local build_log="$BA_HOME/frontend_build.log"
  local status="failed"

  # `npm run build` (scripts/build-atomic.mjs) builds into a temp dir, swaps
  # it into dist/ atomically, and keeps the previous build's content-hashed
  # assets so live tabs don't lose their lazy chunks mid-rebuild.
  echo "Building frontend..."
  if (cd "${ACTIVE_DIR:-$DIR}/frontend" && npm run build 2>&1 | tee "$build_log"); then
    status="succeeded"
  else
    echo "Frontend build failed — serving previous build"
  fi

  if [ -n "$request_id" ]; then
    "$PY" - "$RESULT" "$request_id" "$status" "$build_log" <<'PY'
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

result_path = Path(sys.argv[1])
request_id = sys.argv[2]
status = sys.argv[3]
log_path = Path(sys.argv[4])
error = None
if status == "failed":
    try:
        error = log_path.read_text(encoding="utf-8", errors="replace")[-4000:]
    except OSError:
        error = "Frontend build failed; build log was unavailable."

payload = {
    "request_id": request_id,
    "status": status,
    "completed_at": datetime.now(timezone.utc).isoformat(),
    "error": error,
}
tmp_path = result_path.with_suffix(".tmp")
tmp_path.write_text(json.dumps(payload), encoding="utf-8")
os.replace(tmp_path, result_path)
PY
  fi
}

start_frontend_build() {
  local request_id="${1:-}"
  reap_completed_children
  if tracked_child_is_running "$FRONTEND_BUILD_PID"; then
    if [ -n "$request_id" ]; then
      local previous_pid="$FRONTEND_BUILD_PID"
      (wait "$previous_pid" 2>/dev/null || true; build_frontend "$request_id") &
      FRONTEND_BUILD_PID=$!
    fi
    return 0
  fi
  build_frontend "$request_id" &
  FRONTEND_BUILD_PID=$!
}

app_url() {
  echo "http://127.0.0.1:$BACKEND_PORT/"
}

open_first_run_browser() {
  local url="$1"
  if [ "${BETTER_AGENT_NO_BROWSER:-${BETTER_CLAUDE_NO_BROWSER:-0}}" = "1" ]; then
    return 0
  fi
  if [ "$FIRST_RUN_AUTH_BOOTSTRAPPED" -ne 1 ]; then
    return 0
  fi
  if [ "$FIRST_RUN_BROWSER_OPENED" -eq 1 ]; then
    return 0
  fi
  if [ ! -t 0 ]; then
    return 0
  fi

  FIRST_RUN_BROWSER_OPENED=1
  case "$(uname -s)" in
    Darwin)
      open "$url" >/dev/null 2>&1 || true
      ;;
    Linux)
      if command -v xdg-open >/dev/null 2>&1; then
        xdg-open "$url" >/dev/null 2>&1 || true
      fi
      ;;
    MINGW*|MSYS*|CYGWIN*)
      cmd.exe /c start "" "$url" >/dev/null 2>&1 || true
      ;;
  esac
}

start_backend() {
  local bind_host
  local pid_file="$CREDENTIAL_BACKEND_CONTROL_DIR/backend.pid"
  if ! PYTHONPATH="$DIR:$DIR/backend" "$PY" -m restart_request "$FLAG" --clear; then
    echo "Could not clear stale restart intent before backend generation." >&2
    return 1
  fi
  bind_host=$("$PY" - "$BA_HOME/user_prefs.json" <<'PY'
import json
import sys
from pathlib import Path

try:
    prefs = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError):
    prefs = {}

host = prefs.get("network_bind_address", "127.0.0.1")
if host not in ("127.0.0.1", "0.0.0.0"):
    host = "127.0.0.1"
print(host)
PY
)
  # ACTIVE_DIR / BETTER_AGENT_ACTIVE_CHECKOUT are resolved once per loop
  # iteration by the caller before the frontend build, so the built frontend and
  # the backend always target the same checkout. The pointer is written by the
  # switch-control extension; this launcher honors it and reverts on failed
  # starts.
  echo "Starting backend (no --reload) on $bind_host:$BACKEND_PORT..."
  kill_backend_lock_holder
  BACKEND_PORT="$(resolve_port_conflict "$BACKEND_PORT" "backend")"
  export BETTER_CLAUDE_BACKEND_PORT="$BACKEND_PORT"
  export BETTER_CLAUDE_BACKEND_URL="http://127.0.0.1:$BACKEND_PORT"
  export BETTER_AGENT_BACKEND_PORT="$BACKEND_PORT"
  export BETTER_AGENT_BACKEND_URL="http://127.0.0.1:$BACKEND_PORT"
  export BA_BACKEND_PORT="$BACKEND_PORT"
  # The Python supervisor owns uvicorn and its private credential channel. It
  # forwards output to this terminal and the backend log.
  : > "$BACKEND_LOG"
  echo "--- backend start $(date '+%Y-%m-%dT%H:%M:%S%z') port=$BACKEND_PORT ---" >> "$BACKEND_LOG"
  if ! credential_backend_control start \
    --checkout "$ACTIVE_DIR" --host "$bind_host" --port "$BACKEND_PORT" > "$pid_file"; then
    rm -f "$pid_file"
    return 1
  fi
  IFS= read -r BACKEND_PID < "$pid_file"
  rm -f "$pid_file"
  if ! read_backend_status; then
    echo "Credential backend supervisor did not report the new generation." >&2
    return 1
  fi
  BACKEND_GENERATION_ID="$STATUS_GENERATION_ID"
  BACKEND_GENERATION_STARTED_AT="$STATUS_STARTED_AT"
  if [ "$STATUS_PID" != "$BACKEND_PID" ] || [ "$BACKEND_GENERATION_ID" = "-" ] \
    || [ "$BACKEND_GENERATION_STARTED_AT" = "-" ]; then
    echo "Credential backend supervisor reported an invalid new generation." >&2
    return 1
  fi
}

wait_for_backend() {
  local url=""
  while kill -0 "$BACKEND_PID" 2>/dev/null; do
    if curl -fsS "http://127.0.0.1:$BACKEND_PORT/readyz" >/dev/null 2>&1; then
      echo "Backend is ready."
      url="$(app_url)"
      echo "Better Agent is ready: $url"
      open_first_run_browser "$url"
      return 0
    fi
    sleep 0.25
  done
  echo "Backend exited before becoming healthy."
  BACKEND_PID=""
  return 1
}

wait_for_backend_exit() {
  local restart_attempts=0
  local restart_limit=$((GRACEFUL_RESTART_TIMEOUT_SECONDS * 4))

  while process_is_running "$BACKEND_PID"; do
    if [ -f "$FLAG" ]; then
      if [ "$restart_attempts" -eq 0 ]; then
        echo "Restart requested — waiting up to ${GRACEFUL_RESTART_TIMEOUT_SECONDS}s for graceful shutdown..."
      fi
      if [ "$restart_attempts" -ge "$restart_limit" ]; then
        echo "Graceful restart timeout expired; forcing backend shutdown."
        credential_backend_control signal --signal KILL >/dev/null 2>&1 || true
        break
      fi
      restart_attempts=$((restart_attempts + 1))
    fi
    sleep 0.25
  done

  local terminal_attempts=0

  while [ "$terminal_attempts" -lt 100 ]; do
    if ! read_backend_status 2>/dev/null; then
      echo "Credential backend supervisor status failed after backend exit." >&2
      return 1
    fi
    if [ "$STATUS_TERMINAL" = "1" ] \
      && [ "$STATUS_GENERATION_ID" = "$BACKEND_GENERATION_ID" ] \
      && [ "$STATUS_RETURNCODE" != "-" ]; then
      BACKEND_EXIT_CODE="$STATUS_RETURNCODE"
      BACKEND_EXIT_PID="$BACKEND_PID"
      BACKEND_PID=""
      return 0
    fi
    terminal_attempts=$((terminal_attempts + 1))
    sleep 0.05
  done
  echo "Credential backend supervisor did not acknowledge terminal generation." >&2
  return 1
}

PENDING_REFRESH_ID=""
INITIAL_FRONTEND_BUILD_STARTED=0
BACKEND_CRASH_ATTEMPTS=0
BACKEND_HEALTHY_AT=0
BACKEND_CRASH_LIMIT="${BETTER_AGENT_BACKEND_CRASH_LIMIT:-5}"
BACKEND_STABILITY_SECONDS="${BETTER_AGENT_BACKEND_STABILITY_SECONDS:-60}"
case "$BACKEND_CRASH_LIMIT" in
  ''|*[!0-9]*) echo "BETTER_AGENT_BACKEND_CRASH_LIMIT must be an integer." >&2; exit 2 ;;
esac
case "$BACKEND_STABILITY_SECONDS" in
  ''|*[!0-9]*) echo "BETTER_AGENT_BACKEND_STABILITY_SECONDS must be an integer." >&2; exit 2 ;;
esac
if [ "$BACKEND_CRASH_LIMIT" -lt 1 ] || [ "$BACKEND_CRASH_LIMIT" -gt 20 ]; then
  echo "BETTER_AGENT_BACKEND_CRASH_LIMIT must be in 1..20." >&2
  exit 2
fi
if [ "$BACKEND_STABILITY_SECONDS" -lt 1 ] || [ "$BACKEND_STABILITY_SECONDS" -gt 3600 ]; then
  echo "BETTER_AGENT_BACKEND_STABILITY_SECONDS must be in 1..3600." >&2
  exit 2
fi

integrations_enabled() {
  PYTHONPATH="$DIR/backend" "$PY" -c \
    'import installation_profile as p; print("1" if p.capability_requested(p.INTEGRATIONS) else "0")'
}

prepare_daemon_host_for_backend() {
  if [ "$(integrations_enabled)" = "1" ]; then
    return
  fi
  stop_child_process "daemon host" "$DAEMON_HOST_PID"
  DAEMON_HOST_PID=""
  kill_matching_processes \
    "Better Agent extension daemon host" \
    "$DIR.*-m daemonhost"
}

start_daemon_host_after_backend_ready() {
  if [ "$(integrations_enabled)" != "1" ] || tracked_child_is_running "$DAEMON_HOST_PID"; then
    return
  fi
  PYTHONPATH="$DIR" "$PY" -m daemonhost &
  DAEMON_HOST_PID=$!
}

prepare_daemon_host_for_backend
# shellcheck source=scripts/switch_launch.sh
source "$DIR/scripts/switch_launch.sh"
if [ "${BETTER_AGENT_RUN_SH_TEST_NORMAL_EXIT_CLEANUP:-0}" = "1" ]; then
  (sleep 30 & wait) &
  FRONTEND_BUILD_PID=$!
  (sleep 30 & wait) &
  DAEMON_HOST_PID=$!
  ZAI_STARTUP_CHECK_PID="$("$PY" - <<'PY'
import subprocess

proc = subprocess.Popen(
    ["sleep", "30"],
    stdin=subprocess.DEVNULL,
    stdout=subprocess.DEVNULL,
    stderr=subprocess.DEVNULL,
    start_new_session=True,
)
print(proc.pid)
PY
)"
  echo "Normal exit cleanup test ready: frontend=$FRONTEND_BUILD_PID daemon=$DAEMON_HOST_PID checker=$ZAI_STARTUP_CHECK_PID"
else
  start_credential_backend_supervisor
  while true; do
    # Line switching: run the backend from the active checkout (dev/main worktree)
    # named by the pointer. Resolve it every iteration — a switch or an auto-revert
    # changes it between restarts, and the frontend build below must target the
    # same checkout the backend will import.
    ACTIVE_DIR="$(resolve_active_checkout "$PY" "$DIR" "$DIR")"
    SWITCH_REQUEST_ID="$(PYTHONPATH="$DIR" "$PY" -m daemonhost.pointer request-id 2>/dev/null || true)"
    export BETTER_AGENT_ACTIVE_CHECKOUT="$ACTIVE_DIR"
    if [ "$ACTIVE_DIR" != "$DIR" ]; then
      echo "Active checkout: $ACTIVE_DIR"
    fi

    # The backend imports the active checkout's built frontend at import time.
    # When no dist exists yet, how it gets built depends on why:
    #  - A line switch to a never-built checkout must build synchronously first,
    #    because the build result decides whether to revert the switch.
    #  - A cold clone (no switch in flight) uses serve-then-build: the backend
    #    starts against mount_frontend()'s placeholder, the frontend builds in
    #    the background, and the backend self-restarts once the build lands.
    # A warm checkout keeps the fast "serve the previous build while rebuilding
    # in the background" path.
    if active_frontend_needs_build "$ACTIVE_DIR"; then
      if PYTHONPATH="$DIR" "$PY" -m daemonhost.pointer is-switching 2>/dev/null; then
        build_frontend "$PENDING_REFRESH_ID"
        PENDING_REFRESH_ID=""
        # If the synchronous build produced no dist (the target checkout's own
        # build failed), starting the backend would crash in mount_frontend().
        # Revert the in-flight switch rather than crash-looping on its target.
        if active_frontend_needs_build "$ACTIVE_DIR" \
          && PYTHONPATH="$DIR" "$PY" -m daemonhost.pointer revert-if-switching \
            --reason "frontend build produced no dist for the switch target" \
            --request-id "$SWITCH_REQUEST_ID" 2>/dev/null; then
          echo "Line switch failed — target frontend did not build — recovering previous checkout..."
          continue
        fi
      else
        start_frontend_build "$PENDING_REFRESH_ID"
        PENDING_REFRESH_ID=""
      fi
    elif [ "$INITIAL_FRONTEND_BUILD_STARTED" -eq 0 ]; then
      start_frontend_build ""
    fi
    INITIAL_FRONTEND_BUILD_STARTED=1

    prepare_daemon_host_for_backend
    if ! start_backend; then
      echo "Backend generation failed to start safely."
      break
    fi
    # Capture health without aborting under `set -e` so line-switch recovery runs.
    if wait_for_backend; then
      BACKEND_HEALTHY=1
      BACKEND_HEALTHY_AT=$SECONDS
    else
      BACKEND_HEALTHY=0
    fi

    if [ "$BACKEND_HEALTHY" -ne 1 ]; then
      # Auto-revert a failed line switch: only fires when a switch is in
      # flight, so an ordinary crash never flips checkouts.
      if PYTHONPATH="$DIR" "$PY" -m daemonhost.pointer revert-if-switching \
        --reason "backend failed to become healthy" --request-id "$SWITCH_REQUEST_ID" 2>/dev/null; then
        echo "Line switch failed — recovering to a runnable checkout..."
        continue
      fi
      echo "Backend never became healthy; exiting."
      break
    fi
    PYTHONPATH="$DIR" "$PY" -m daemonhost.pointer confirm-healthy \
      --running-dir "$ACTIVE_DIR" --request-id "$SWITCH_REQUEST_ID" 2>/dev/null || true
    start_daemon_host_after_backend_ready

    if [ -n "$PENDING_REFRESH_ID" ]; then
      start_frontend_build "$PENDING_REFRESH_ID"
      PENDING_REFRESH_ID=""
    fi

    # Block until uvicorn exits. Restart-requested exits are bounded so a stuck
    # shutdown does not leave the UI waiting forever.
    if ! wait_for_backend_exit; then
      echo "Backend lifecycle state is unsafe; stopping launcher."
      break
    fi

    if [ -f "$FLAG" ]; then
      if ! PENDING_REFRESH_ID="$(PYTHONPATH="$DIR:$DIR/backend" "$PY" -m restart_request \
        "$FLAG" --not-before "$BACKEND_GENERATION_STARTED_AT")"; then
        echo "Restart request was invalid; stopping launcher." >&2
        break
      fi
      if [ -n "$PENDING_REFRESH_ID" ]; then
        BACKEND_CRASH_ATTEMPTS=0
        PYTHONPATH="$DIR" "$PY" -m desktop.backend_exit_journal \
          --state-root "$BA_HOME" --source run.sh --exit-code "$BACKEND_EXIT_CODE" \
          --classification refresh --decision restart \
          --generation-id "$BACKEND_GENERATION_ID" --pid "$BACKEND_EXIT_PID" \
          --checkout "$ACTIVE_DIR" --request-id "$PENDING_REFRESH_ID" || true
        echo "Restart requested — restarting backend..."
        continue
      fi
    fi

    RECOVERY_DECISION="$(PYTHONPATH="$DIR" "$PY" -m desktop.backend_recovery_policy \
      --attempts "$BACKEND_CRASH_ATTEMPTS" \
      --healthy-seconds "$((SECONDS - BACKEND_HEALTHY_AT))" \
      --limit "$BACKEND_CRASH_LIMIT" \
      --stability-seconds "$BACKEND_STABILITY_SECONDS")"
    IFS='|' read -r RECOVERY_ACTION BACKEND_CRASH_ATTEMPTS BACKEND_BACKOFF <<EOF
$RECOVERY_DECISION
EOF
    if [ "$RECOVERY_ACTION" = "circuit_open" ]; then
      PYTHONPATH="$DIR" "$PY" -m desktop.backend_exit_journal \
        --state-root "$BA_HOME" --source run.sh --exit-code "$BACKEND_EXIT_CODE" \
        --classification unexpected --decision circuit_open \
        --restart-attempt "$BACKEND_CRASH_ATTEMPTS" \
        --generation-id "$BACKEND_GENERATION_ID" --pid "$BACKEND_EXIT_PID" \
        --checkout "$ACTIVE_DIR" || true
      echo "Backend crash recovery circuit opened after $BACKEND_CRASH_ATTEMPTS attempts."
      break
    fi
    PYTHONPATH="$DIR" "$PY" -m desktop.backend_exit_journal \
      --state-root "$BA_HOME" --source run.sh --exit-code "$BACKEND_EXIT_CODE" \
      --classification unexpected --decision restart \
      --restart-attempt "$BACKEND_CRASH_ATTEMPTS" \
      --generation-id "$BACKEND_GENERATION_ID" --pid "$BACKEND_EXIT_PID" \
      --checkout "$ACTIVE_DIR" || true
    echo "Backend exited unexpectedly (code $BACKEND_EXIT_CODE) — restarting in ${BACKEND_BACKOFF}s..."
    sleep "$BACKEND_BACKOFF"
    continue
  done
fi

reap_completed_children
stop_child_process "frontend build" "$FRONTEND_BUILD_PID"
stop_child_process "daemon host" "$DAEMON_HOST_PID"
stop_credential_backend_supervisor