claude-smart 0.2.48 → 0.2.50

package/plugin/scripts/backend-service.sh

@@ -4,6 +4,8 @@
 # so the SessionStart hook doesn't block the session.
 #
 # Subcommands:
+#   preflight     verify that this plugin can import its bundled Reflexio
+#                 runtime without changing any running service.
 #   start         probe /health; if nothing we recognize is on the port,
 #                 spawn the prepared venv's `reflexio services start --only
 #                 backend --no-reload` detached. Polls /health briefly so first
@@ -27,7 +29,7 @@ fi
 claude_smart_prepend_astral_bins
 claude_smart_source_reflexio_env
 
-PORT=8071
+PORT="${BACKEND_PORT:-8071}"
 EMBEDDING_PORT="${EMBEDDING_PORT:-8072}"
 # Pass through to `reflexio services start/stop` so the spawned backend
 # binds to PORT instead of reflexio's library default (8081).
@@ -45,7 +47,7 @@ export REFLEXIO_DEFAULT_ORG_ID="claude-smart"
 # Load claude-smart's env from ~/.claude-smart/.env instead of the reflexio
 # default ~/.reflexio/.env, so an OSS reflexio backend's .env on this machine
 # can't leak in. The data dir is independent (LOCAL_STORAGE_PATH), so both still
-# share ~/.reflexio/data. Must stay in sync with env_config.REFLEXIO_ENV_PATH and
+# share ~/.reflexio/data. Must stay in sync with env_config.CLAUDE_SMART_ENV_PATH and
 # the source path in _lib.sh (claude_smart_source_reflexio_env).
 export REFLEXIO_ENV_FILE="$HOME/.claude-smart/.env"
 
@@ -63,13 +65,51 @@ fi
 # explicitly if we can resolve it from our own (post-login-path) PATH.
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "backend-service.sh" "$@"
+PLUGIN_ROOT_CANONICAL="$(cd "$PLUGIN_ROOT" 2>/dev/null && pwd -P || printf '%s\n' "$PLUGIN_ROOT")"
+VENDORED_REFLEXIO="$PLUGIN_ROOT_CANONICAL/vendor/reflexio"
+VENDORED_REFLEXIO_FOR_PYTHON="$VENDORED_REFLEXIO"
+if claude_smart_is_windows; then
+  VENDORED_REFLEXIO_FOR_PYTHON="$(claude_smart_to_windows_path "$VENDORED_REFLEXIO")"
+fi
+export CLAUDE_SMART_REFLEXIO_VENDOR_ROOT="$VENDORED_REFLEXIO_FOR_PYTHON"
+
+plugin_version_from_root() {
+  root="$1"
+  version="$(
+    sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+      "$root/.codex-plugin/plugin.json" 2>/dev/null | head -n1
+  )"
+  if [ -z "$version" ]; then
+    version="$(
+      sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+        "$root/package.json" 2>/dev/null | head -n1
+    )"
+  fi
+  if [ -z "$version" ]; then
+    version="$(
+      sed -n 's/^[[:space:]]*version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' \
+        "$root/pyproject.toml" 2>/dev/null | head -n1
+    )"
+  fi
+  printf '%s\n' "${version:-unknown}"
+}
+
+plugin_root_has_version_manifest() {
+  root="$1"
+  [ -f "$root/.codex-plugin/plugin.json" ] || [ -f "$root/package.json" ] || [ -f "$root/pyproject.toml" ]
+}
+
+PLUGIN_VERSION="$(plugin_version_from_root "$PLUGIN_ROOT_CANONICAL")"
 
 if [ -z "${CLAUDE_SMART_CLI_PATH:-}" ]; then
-  if [ "${CLAUDE_SMART_HOST:-claude-code}" = "opencode" ] && command -v opencode >/dev/null 2>&1; then
+  if [ "${CLAUDE_SMART_HOST:-claude-code}" = "opencode" ]; then
     # Preserve Reflexio's Claude CLI provider contract while routing
-    # generation through the user's authenticated OpenCode setup.
+    # generation through the user's authenticated OpenCode setup. The bridge
+    # resolves opencode from CLAUDE_SMART_OPENCODE_PATH or PATH; don't require
+    # Git Bash's PATH to match the installer shell's PATH here.
     claude_smart_prepend_node_bins
-    export CLAUDE_SMART_CLI_PATH="$PLUGIN_ROOT/scripts/opencode-claude-compat"
+    CLAUDE_SMART_CLI_PATH="$(claude_smart_opencode_compat_path "$PLUGIN_ROOT")"
+    export CLAUDE_SMART_CLI_PATH
   elif [ "${CLAUDE_SMART_HOST:-claude-code}" = "codex" ]; then
     # Reflexio's provider still calls CLAUDE_SMART_CLI_PATH with Claude CLI
     # flags. Use a small compatibility executable that translates that narrow
@@ -85,7 +125,12 @@ if [ -z "${CLAUDE_SMART_CLI_PATH:-}" ]; then
 fi
 
 STATE_DIR="$HOME/.claude-smart"
-PID_FILE="$STATE_DIR/backend.pid"
+backend_pid_key="$(
+  printf '%s' "$PLUGIN_ROOT_CANONICAL" | cksum 2>/dev/null | awk '{print $1}' || true
+)"
+backend_pid_key="${backend_pid_key:-default}"
+PID_FILE="$STATE_DIR/backend.$backend_pid_key.pid"
+SHARED_PID_FILE="$STATE_DIR/backend.pid"
 LOG_FILE="$STATE_DIR/backend.log"
 LOG_MAX_BYTES="$(claude_smart_log_max_bytes)"
 mkdir -p "$STATE_DIR"
@@ -93,14 +138,19 @@ claude_smart_trim_log_file "$LOG_FILE" "$LOG_MAX_BYTES"
 
 emit_ok() { claude_smart_emit_continue; }
 
+# Reason string for a failed bundled-Reflexio preflight. Shared by every site
+# that reports it so the remedy text in emit_start_failure stays in sync.
+VENDOR_PREFLIGHT_FAILURE="bundled Reflexio import preflight failed"
+
 emit_start_failure() {
   reason="$1"
   if py=$(claude_smart_resolve_python 2>/dev/null); then
-    "$py" - "$reason" <<'PY'
+    "$py" - "$reason" "$VENDOR_PREFLIGHT_FAILURE" <<'PY'
 import json
 import sys
 
 reason = sys.argv[1].strip()
+vendor_preflight_failure = sys.argv[2]
 message = (
     "> **claude-smart learning backend is not running.** "
     "Interactions are being buffered locally, but learning will not publish "
@@ -108,10 +158,19 @@ message = (
 )
 if reason:
     message += f">\n> Last startup error: `{reason}`\n"
-message += (
-    ">\n> Make sure the local model provider is available: Claude Code needs "
-    "`claude`, Codex needs `codex`. Then run `/claude-smart:restart`."
-)
+if reason == vendor_preflight_failure:
+    # /claude-smart:restart cannot repair this: the bundled Reflexio runtime
+    # only ships in the npm artifact, so the cache has to be replaced.
+    message += (
+        ">\n> The bundled Reflexio runtime is missing or unusable. Repair it "
+        "with `npx claude-smart update`, then restart Claude Code."
+    )
+else:
+    message += (
+        ">\n> Make sure the local model provider is available: Claude Code needs "
+        "`claude`, Codex needs `codex`, and OpenCode needs `opencode`. "
+        "Then run `/claude-smart:restart`."
+    )
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",
@@ -130,79 +189,592 @@ kill_group() {
   claude_smart_kill_tree "$1"
 }
 
-# True if /health returns 200. Reflexio's /health is a plain GET with no
-# marker header, so we can't distinguish our backend from someone else's
-# reflexio on the same port — if you run two reflexio instances on 8071
-# you'll get collision regardless of what we do here.
+# True if /health returns 200, regardless of runtime identity. Used only for
+# generic liveness; ownership checks inspect the listener process.
 backend_healthy() {
   command -v curl >/dev/null 2>&1 || return 1
-  curl -sf -o /dev/null "http://127.0.0.1:$PORT/health" 2>/dev/null
+  curl -sf --connect-timeout 1 --max-time 1 -o /dev/null "http://127.0.0.1:$PORT/health" 2>/dev/null
+}
+
+wait_for_health() {
+  probe_fn="$1"
+  attempts="$2"
+  interval="$3"
+  while [ "$attempts" -gt 0 ]; do
+    "$probe_fn" && return 0
+    attempts=$((attempts - 1))
+    sleep "$interval"
+  done
+  "$probe_fn"
+}
+
+log_embedding_degraded() {
+  claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+    "[claude-smart] backend: Embedding service did not become healthy on port $EMBEDDING_PORT; semantic retrieval remains unavailable until the local embedding daemon recovers"
+}
+
+# Best-effort port probe. curl catches responsive HTTP listeners; /dev/tcp
+# catches other listeners where bash supports it. Used to avoid stomping on
+# a foreign listener with a failed-to-start uvicorn.
+port_occupied() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -sf --max-time 2 -o /dev/null "http://127.0.0.1:$PORT" 2>/dev/null && return 0
+  fi
+  (echo >"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null
+}
+
+pid_details() {
+  pid="$1"
+  seen=" "
+  depth=0
+  while [ -n "$pid" ] && [ "$pid" != "0" ] && [ "$depth" -lt 6 ]; do
+    case "$seen" in *" $pid "*) break ;; esac
+    seen="$seen$pid "
+    {
+      printf 'pid=%s ' "$pid"
+      claude_smart_pid_command "$pid" 2>/dev/null || true
+      if command -v lsof >/dev/null 2>&1; then
+        lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n/cwd=/p' || true
+      fi
+    }
+    parent="$(claude_smart_pid_parent "$pid" 2>/dev/null || true)"
+    [ -n "$parent" ] && [ "$parent" != "$pid" ] || break
+    pid="$parent"
+    depth=$((depth + 1))
+  done | tr '\n' ' '
+}
+
+marked_backend_ancestor_pid() {
+  pid="$1"
+  seen=" "
+  depth=0
+  while [ -n "$pid" ] && [ "$pid" != "0" ] && [ "$depth" -lt 6 ]; do
+    case "$seen" in *" $pid "*) break ;; esac
+    seen="$seen$pid "
+    cmdline="$(claude_smart_pid_command "$pid" | tr '\n' ' ' || true)"
+    case "$cmdline" in
+      *backend-python-runner.py*--claude-smart-backend=1*)
+        printf '%s\n' "$pid"
+        return 0
+        ;;
+    esac
+    parent="$(claude_smart_pid_parent "$pid" 2>/dev/null || true)"
+    [ -n "$parent" ] && [ "$parent" != "$pid" ] || break
+    pid="$parent"
+    depth=$((depth + 1))
+  done
+  return 1
+}
+
+stop_backend_pids() {
+  pids="$1"
+  [ -n "$pids" ] || return 0
+  targets=""
+  for pid in $pids; do
+    target="$(marked_backend_ancestor_pid "$pid" 2>/dev/null || true)"
+    for candidate in ${target:-} "$pid"; do
+      [ -n "$candidate" ] || continue
+      case " $targets " in *" $candidate "*) ;; *) targets="$targets $candidate" ;; esac
+    done
+  done
+  for target in $targets; do
+    kill_group "$target"
+  done
+}
+
+looks_like_claude_smart_backend_pid() {
+  pid="$1"
+  text="$(pid_details "$pid")"
+  [ -n "$text" ] || return 1
+  case "$text" in
+    *--claude-smart-backend=1*|*--claude-smart-reflexio-vendor-root=*|*--claude-smart-plugin-root=*|*"reflexioai/claude-smart"*|*"reflexioai\\claude-smart"*)
+      return 0
+      ;;
+  esac
+  for token in $text; do
+    value="$(pid_token_path_entry "$token")"
+    path_is_or_under_root "$PLUGIN_ROOT_CANONICAL" "$value" && return 0
+  done
+  return 1
+}
+
+is_claude_smart_backend_pid() {
+  pid="$1"
+  backend_pid_command_matches "$pid" && looks_like_claude_smart_backend_pid "$pid"
+}
+
+path_is_or_under_root() {
+  root="$1"
+  value="$2"
+  [ -n "$root" ] && [ -n "$value" ] || return 1
+  case "$value" in
+    "$root"|"$root"/*|"$root"\\*) return 0 ;;
+  esac
+  return 1
+}
+
+pid_token_path_entry() {
+  token="$1"
+  value="${token#*=}"
+  # PYTHONPATH can hold multiple roots; split path-list suffixes without
+  # treating a Windows drive prefix like C:\... as a separator.
+  case "$value" in
+    *";"*) value="${value%%;*}" ;;
+    [A-Za-z]:\\*) ;;
+    *) value="${value%%:*}" ;;
+  esac
+  printf '%s\n' "$value"
+}
+
+pid_vendor_root() {
+  pid="$1"
+  text="$(pid_details "$pid")"
+  [ -n "$text" ] || return 1
+  for token in $text; do
+    case "$token" in
+      --claude-smart-reflexio-vendor-root=*)
+        printf '%s\n' "${token#--claude-smart-reflexio-vendor-root=}"
+        return 0
+        ;;
+      --claude-smart-plugin-root=*)
+        printf '%s/vendor/reflexio\n' "${token#--claude-smart-plugin-root=}"
+        return 0
+        ;;
+    esac
+    value="$(pid_token_path_entry "$token")"
+    case "$value" in
+      */vendor/reflexio|*\\vendor\\reflexio)
+        root="$(plugin_root_from_vendor_root "$value" 2>/dev/null || true)"
+        if [ -n "$root" ] && plugin_root_has_version_manifest "$root"; then
+          printf '%s\n' "$value"
+          return 0
+        fi
+        ;;
+    esac
+  done
+  return 1
+}
+
+plugin_root_from_vendor_root() {
+  vendor="$1"
+  case "$vendor" in
+    */vendor/reflexio) printf '%s\n' "${vendor%/vendor/reflexio}"; return 0 ;;
+    *\\vendor\\reflexio) printf '%s\n' "${vendor%\\vendor\\reflexio}"; return 0 ;;
+  esac
+  return 1
+}
+
+pid_plugin_root() {
+  text="$(pid_details "$1")"
+  for token in $text; do
+    case "$token" in
+      --claude-smart-plugin-root=*)
+        printf '%s\n' "${token#--claude-smart-plugin-root=}"
+        return 0
+        ;;
+    esac
+  done
+  vendor="$(pid_vendor_root "$1" 2>/dev/null || true)"
+  if [ -n "$vendor" ]; then
+    plugin_root_from_vendor_root "$vendor" && return 0
+  fi
+  for token in $text; do
+    case "$token" in
+      cwd=*)
+        root="${token#cwd=}"
+        if plugin_root_has_version_manifest "$root"; then
+          printf '%s\n' "$root"
+          return 0
+        fi
+        ;;
+    esac
+  done
+  return 1
+}
+
+pid_plugin_version() {
+  text="$(pid_details "$1")"
+  for token in $text; do
+    case "$token" in
+      --claude-smart-version=*)
+        printf '%s\n' "${token#--claude-smart-version=}"
+        return 0
+        ;;
+    esac
+  done
+  root="$(pid_plugin_root "$1" 2>/dev/null || true)"
+  [ -n "$root" ] || { printf '%s\n' "unknown"; return 0; }
+  plugin_version_from_root "$root"
+}
+
+pid_uses_current_vendor_root() {
+  pid="$1"
+  text="$(pid_details "$pid")"
+  [ -n "$text" ] || return 1
+  for token in $text; do
+    case "$token" in
+      --claude-smart-plugin-root=*)
+        value="${token#--claude-smart-plugin-root=}"
+        path_is_or_under_root "$PLUGIN_ROOT_CANONICAL" "$value" && return 0
+        ;;
+      --claude-smart-reflexio-vendor-root=*)
+        value="${token#--claude-smart-reflexio-vendor-root=}"
+        path_is_or_under_root "$VENDORED_REFLEXIO" "$value" && return 0
+        path_is_or_under_root "$VENDORED_REFLEXIO_FOR_PYTHON" "$value" && return 0
+        ;;
+      *)
+        value="$(pid_token_path_entry "$token")"
+        path_is_or_under_root "$VENDORED_REFLEXIO" "$value" && return 0
+        path_is_or_under_root "$VENDORED_REFLEXIO_FOR_PYTHON" "$value" && return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+backend_version_core_parts() {
+  version="$1"
+  printf '%s\n' "$version" \
+    | sed -n 's/^\([0-9][0-9]*\)\.\([0-9][0-9]*\)\.\([0-9][0-9]*\)$/\1 \2 \3/p'
+}
+
+backend_version_older_than() {
+  actual_version_input="$1"
+  target_version_input="$2"
+  actual_core="$(backend_version_core_parts "$actual_version_input")"
+  target_core="$(backend_version_core_parts "$target_version_input")"
+  [ -n "$actual_core" ] && [ -n "$target_core" ] || return 1
+
+  set -- $actual_core
+  actual_major="$1"; actual_minor="$2"; actual_patch="$3"
+  set -- $target_core
+  target_major="$1"; target_minor="$2"; target_patch="$3"
+
+  [ "$actual_major" -lt "$target_major" ] && return 0
+  [ "$actual_major" -gt "$target_major" ] && return 1
+  [ "$actual_minor" -lt "$target_minor" ] && return 0
+  [ "$actual_minor" -gt "$target_minor" ] && return 1
+  [ "$actual_patch" -lt "$target_patch" ] && return 0
+  return 1
+}
+
+backend_pid_current_or_compatible() {
+  pid="$1"
+  pid_uses_current_vendor_root "$pid" && return 0
+  [ "$PLUGIN_VERSION" = "unknown" ] && return 0
+  running_version="$(pid_plugin_version "$pid")"
+  [ "$running_version" = "unknown" ] && return 0
+  ! backend_version_older_than "$running_version" "$PLUGIN_VERSION"
+}
+
+backend_pid_strictly_older_than_plugin() {
+  pid="$1"
+  [ "$PLUGIN_VERSION" != "unknown" ] || return 1
+  pid_uses_current_vendor_root "$pid" && return 1
+  running_version="$(pid_plugin_version "$pid")"
+  [ "$running_version" != "unknown" ] || return 1
+  backend_version_older_than "$running_version" "$PLUGIN_VERSION"
+}
+
+backend_listener_pids() {
+  claude_smart_port_listener_pids "$PORT"
+}
+
+classify_backend_listener() {
+  pids="$(backend_listener_pids || true)"
+  [ -n "$pids" ] || { printf '%s\n' "free"; return 0; }
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid"; then
+      printf '%s\n' "claude_smart"
+      return 0
+    fi
+  done
+  printf '%s\n' "foreign"
+}
+
+backend_owned_by_current_vendor() {
+  backend_healthy || return 1
+  pids="$(backend_listener_pids)"
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && pid_uses_current_vendor_root "$pid"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+backend_owned_by_stale_claude_smart() {
+  pids="$(backend_listener_pids)"
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && backend_pid_strictly_older_than_plugin "$pid"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+backend_current_or_compatible() {
+  backend_healthy || return 1
+  pids="$(backend_listener_pids)"
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && backend_pid_current_or_compatible "$pid"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+embedding_owned_by_current_vendor() {
+  [ "${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-}" = "1" ] || return 0
+  pids="$(claude_smart_port_listener_pids "$EMBEDDING_PORT")"
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && pid_uses_current_vendor_root "$pid"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+embedding_current_or_compatible() {
+  [ "${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-}" = "1" ] || return 0
+  pids="$(claude_smart_port_listener_pids "$EMBEDDING_PORT")"
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && backend_pid_current_or_compatible "$pid"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+verify_bundled_reflexio_import() {
+  python_bin="$1"
+  pythonpath="$2"
+  vendor_root_for_python="$3"
+  [ -d "$VENDORED_REFLEXIO/reflexio" ] || {
+    echo "bundled Reflexio package not found at $VENDORED_REFLEXIO" >&2
+    return 1
+  }
+  PYTHONPATH="$pythonpath" "$python_bin" - "$vendor_root_for_python" <<'PY'
+from pathlib import Path
+import sys
+
+vendor = Path(sys.argv[1]).resolve()
+try:
+    import reflexio
+except Exception as exc:
+    print(f"failed to import bundled reflexio from {vendor}: {exc}", file=sys.stderr)
+    raise SystemExit(1)
+
+module = Path(reflexio.__file__).resolve()
+try:
+    module.relative_to(vendor)
+except ValueError:
+    print(
+        f"reflexio import resolved outside bundled vendor: {module} (expected under {vendor})",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+PY
+}
+
+prepare_backend_import_context() {
+  backend_pythonpath="${PYTHONPATH:-}"
+  if [ -d "$VENDORED_REFLEXIO/reflexio" ]; then
+    vendor_pythonpath="$VENDORED_REFLEXIO"
+    pythonpath_sep=":"
+    if claude_smart_is_windows; then
+      # Native Windows Python expects ;-separated Windows-style paths in
+      # PYTHONPATH; MSYS does not auto-convert arbitrary env vars.
+      pythonpath_sep=";"
+      vendor_pythonpath="$VENDORED_REFLEXIO_FOR_PYTHON"
+    fi
+    backend_pythonpath="$vendor_pythonpath${backend_pythonpath:+$pythonpath_sep$backend_pythonpath}"
+  fi
+  backend_python="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
 }
 
-# True only if the recorded PID is alive AND /health responds. A stale
-# PID file from a crashed backend is not enough — we must see the port
-# actually answer, so next hook retries cleanly.
+# Repair the vendored install if its version drifted, then prove this plugin
+# can import its own bundled Reflexio. Callers run this before any action that
+# would stop or replace a running service.
+preflight_bundled_reflexio_runtime() {
+  ensure_vendored_reflexio_active || return 1
+  prepare_backend_import_context
+  verify_bundled_reflexio_import "$backend_python" "$backend_pythonpath" "$VENDORED_REFLEXIO_FOR_PYTHON"
+}
+
+# True only if the recorded PID is alive, /health responds, and the listener
+# process is using this package's bundled Reflexio import path.
 is_our_backend_running() {
   if [ -f "$PID_FILE" ]; then
     pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
-    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
-      backend_healthy && return 0
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && backend_pid_command_matches "$pid"; then
+      if command -v curl >/dev/null 2>&1; then
+        backend_healthy && backend_pid_current_or_compatible "$pid" && return 0
+      else
+        backend_pid_current_or_compatible "$pid" && return 0
+      fi
     fi
   fi
-  # Recover from a missing PID file if a foreign-but-functional reflexio
-  # is already serving — no need to start a second one.
-  backend_healthy && return 0
+  # Recover from a missing PID file only when the listener proves it belongs
+  # to a compatible claude-smart package. A generic healthy service is not
+  # enough, and a known older claude-smart package is restarted later.
+  backend_current_or_compatible && return 0
   return 1
 }
 
-# True if *anything* is listening on the port (even non-HTTP). Used to
-# avoid stomping on a foreign listener with a failed-to-start uvicorn.
-port_occupied() {
-  (echo >"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null
+stop_backend_listener_if_owned() {
+  pids="$(backend_listener_pids)"
+  [ -n "$pids" ] || return 1
+  ours=""
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && { pid_uses_current_vendor_root "$pid" || backend_pid_strictly_older_than_plugin "$pid"; }; then
+      ours="$ours $pid"
+    fi
+  done
+  [ -n "$ours" ] || return 1
+  stop_backend_pids "$ours"
 }
 
-# Reap listeners still holding the given port after the PID file kill
-# when their command line matches one of the supplied patterns. Filters
-# by cmdline so we don't knock over an
-# unrelated service a user has bound there — symmetric with start's
-# refusal to stomp on a foreign listener. Silent on failure.
-reap_port_listeners() {
-  port="${1:-$PORT}"
-  shift || true
-  [ "$#" -eq 0 ] && return 0
-  command -v lsof >/dev/null 2>&1 || return 0
-  candidates=$(lsof -ti:"$port" 2>/dev/null) || candidates=""
-  [ -z "$candidates" ] && return 0
-  ours=""
-  for pid in $candidates; do
-    cmdline=$(ps -p "$pid" -o command= 2>/dev/null || true)
-    for pattern in "$@"; do
-      if [[ "$cmdline" == $pattern ]]; then
-        ours="$ours $pid"
-        break
-      fi
-    done
+stop_stale_backend_listener_if_owned() {
+  backend_owned_by_stale_claude_smart || return 1
+  stale=""
+  for pid in $(backend_listener_pids); do
+    if is_claude_smart_backend_pid "$pid" && backend_pid_strictly_older_than_plugin "$pid"; then
+      stale="$stale $pid"
+    fi
   done
-  [ -z "$ours" ] && return 0
-  # shellcheck disable=SC2086
-  kill -TERM $ours 2>/dev/null || true
-  sleep 1
-  remaining=""
-  for pid in $ours; do
-    kill -0 "$pid" 2>/dev/null && remaining="$remaining $pid"
+  [ -n "$stale" ] || return 1
+  stop_backend_pids "$stale"
+}
+
+stop_stale_embedding_listener_if_owned() {
+  [ "${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-}" = "1" ] || return 0
+  pids="$(claude_smart_port_listener_pids "$EMBEDDING_PORT")"
+  [ -n "$pids" ] || return 0
+  ours=""
+  for pid in $pids; do
+    if is_claude_smart_backend_pid "$pid" && backend_pid_strictly_older_than_plugin "$pid"; then
+      ours="$ours $pid"
+    fi
   done
-  [ -z "$remaining" ] && return 0
-  # shellcheck disable=SC2086
-  kill -KILL $remaining 2>/dev/null || true
+  [ -n "$ours" ] || return 0
+  stop_backend_pids "$ours"
 }
 
 # Describe what (if anything) is currently listening on $1. Returns
-# "<command> (pid <pid>)" or empty if the port is free or lsof is
-# unavailable. Used to make port-conflict log lines diagnosable.
+# "<command> (pid <pid>)" or empty if the port is free or no platform probe is
+# available. Used to make port-conflict log lines diagnosable.
 port_holder() {
-  command -v lsof >/dev/null 2>&1 || return 0
-  lsof -i:"$1" -sTCP:LISTEN -P -n 2>/dev/null \
-    | awk 'NR==2 {print $1" (pid "$2")"; exit}'
+  claude_smart_port_holder "$1"
+}
+
+recorded_backend_pid() {
+  [ -f "$PID_FILE" ] || return 1
+  pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
+  [ -n "$pid" ] || return 1
+  printf '%s\n' "$pid"
+}
+
+shared_backend_pid() {
+  [ -f "$SHARED_PID_FILE" ] || return 1
+  pid=$(cat "$SHARED_PID_FILE" 2>/dev/null || echo "")
+  [ -n "$pid" ] || return 1
+  printf '%s\n' "$pid"
+}
+
+backend_pid_command_matches() {
+  pid="$1"
+  cmdline="$(claude_smart_pid_command "$pid" | tr '\n' ' ' || true)"
+  [ -n "$cmdline" ] || return 1
+  case "$cmdline" in
+    *backend-python-runner.py*--claude-smart-backend=1*services*start*|*reflexio.cli*services*start*|*reflexio.server*|*uvicorn*reflexio*|*reflexio*uvicorn*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+recorded_backend_pid_alive() {
+  pid="$(recorded_backend_pid 2>/dev/null || true)"
+  [ -n "$pid" ] || return 1
+  kill -0 "$pid" 2>/dev/null || return 1
+  backend_pid_command_matches "$pid"
+}
+
+backend_pid_is_own_recorded() {
+  pid="$1"
+  recorded="$(recorded_backend_pid 2>/dev/null || true)"
+  [ -n "$recorded" ] && [ "$pid" = "$recorded" ]
+}
+
+pid_cwd_matches_current_plugin_root() {
+  pid="$1"
+  command -v lsof >/dev/null 2>&1 || return 1
+  cwd="$(
+    lsof -a -p "$pid" -d cwd -Fn 2>/dev/null \
+      | sed -n 's/^n//p' \
+      | head -n 1
+  )"
+  [ -n "$cwd" ] || return 1
+  cwd_canonical="$(cd "$cwd" 2>/dev/null && pwd -P || printf '%s\n' "$cwd")"
+  [ "$cwd_canonical" = "$PLUGIN_ROOT_CANONICAL" ]
+}
+
+backend_pid_is_legacy_same_root_shared() {
+  pid="$1"
+  shared="$(shared_backend_pid 2>/dev/null || true)"
+  [ -n "$shared" ] && [ "$pid" = "$shared" ] || return 1
+  pid_cwd_matches_current_plugin_root "$pid"
+}
+
+backend_start_grace_seconds() {
+  value="${CLAUDE_SMART_BACKEND_START_GRACE_SECONDS:-60}"
+  case "$value" in
+    ''|*[!0-9]*) printf '%s\n' "60" ;;
+    *) printf '%s\n' "$value" ;;
+  esac
+}
+
+recorded_backend_pid_in_startup_grace() {
+  recorded_backend_pid_alive || return 1
+  now="$(claude_smart_now_epoch 2>/dev/null || printf '%s\n' "0")"
+  mtime="$(claude_smart_path_mtime_epoch "$PID_FILE" 2>/dev/null || printf '%s\n' "$now")"
+  age=$((now - mtime))
+  [ "$age" -lt "$(backend_start_grace_seconds)" ]
+}
+
+kill_pid_if_directionally_owned() {
+  pid="$1"
+  [ -n "$pid" ] || return 1
+  kill -0 "$pid" 2>/dev/null || return 1
+  is_claude_smart_backend_pid "$pid" || return 1
+  if pid_uses_current_vendor_root "$pid" \
+    || backend_pid_strictly_older_than_plugin "$pid" \
+    || backend_pid_is_own_recorded "$pid" \
+    || backend_pid_is_legacy_same_root_shared "$pid"; then
+    kill_group "$pid"
+    return 0
+  fi
+  return 1
+}
+
+kill_recorded_backend() {
+  pid="$(recorded_backend_pid 2>/dev/null || true)"
+  if [ -n "$pid" ]; then
+    if ! kill_pid_if_directionally_owned "$pid"; then
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: recorded pid $pid is not owned by this plugin; removing stale root-specific pid file"
+    fi
+    rm -f "$PID_FILE"
+  fi
+  shared_pid="$(shared_backend_pid 2>/dev/null || true)"
+  if [ -n "$shared_pid" ]; then
+    if kill_pid_if_directionally_owned "$shared_pid"; then
+      rm -f "$SHARED_PID_FILE"
+    else
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: shared pid $shared_pid is not owned by this plugin; leaving shared pid file"
+    fi
+  fi
+  return 0
 }
 
 ensure_vendored_reflexio_active() {
@@ -234,27 +806,31 @@ PY
   uv pip install --project "$PLUGIN_ROOT" --python "$plugin_python" --quiet --reinstall --no-deps "$vendor" >&2
 }
 
-# Full shutdown: kill the recorded process group (if any) then sweep
-# both the backend port and the embedding-service port for surviving
-# reflexio listeners. Used by both `stop` and the opt-in `session-end`
-# path so a stale/missing PID file doesn't produce a silent no-op, and
-# so a stale embedding service on EMBEDDING_PORT doesn't block the next
-# fresh boot (e.g. when codex-hook.js falls back to 8072 for the main
-# backend because 8071 is held by another app).
+# Full shutdown: kill the recorded process group (if any) then sweep stale
+# claude-smart-owned backend/embedding listeners. Foreign services on the same
+# ports are left alone.
 full_stop() {
-  if [ -f "$PID_FILE" ]; then
-    kill_group "$(cat "$PID_FILE" 2>/dev/null)"
-    rm -f "$PID_FILE"
-  fi
-  reap_port_listeners "$PORT" '*reflexio*' '*uvicorn*'
+  kill_recorded_backend
+  stop_backend_listener_if_owned || true
   if [ -n "${EMBEDDING_PORT:-}" ] && [ "$EMBEDDING_PORT" != "$PORT" ]; then
-    reap_port_listeners "$EMBEDDING_PORT" \
-      '*reflexio.server.llm.embedding_service:app*' \
-      '*reflexio*embedding_service*'
+    stop_stale_embedding_listener_if_owned || true
   fi
 }
 
 case "$CMD" in
+  preflight)
+    if claude_smart_reflexio_url_is_remote \
+      || [ "${CLAUDE_SMART_BACKEND_AUTOSTART:-1}" = "0" ]; then
+      exit 0
+    fi
+    if ! preflight_bundled_reflexio_runtime; then
+      echo "claude-smart backend preflight failed ($VENDOR_PREFLIGHT_FAILURE);" \
+        "existing services were not changed" >&2
+      echo "Repair the bundled runtime with: npx claude-smart update" >&2
+      exit 1
+    fi
+    exit 0
+    ;;
   start)
     if claude_smart_is_internal_invocation_env; then
       emit_ok; exit 0
@@ -268,19 +844,47 @@ case "$CMD" in
     if [ "${CLAUDE_SMART_BACKEND_AUTOSTART:-1}" = "0" ]; then
       emit_ok; exit 0
     fi
-    if is_our_backend_running; then emit_ok; exit 0; fi
-    if port_occupied; then
-      # Something answered the TCP probe but /health didn't — don't
-      # start a second uvicorn on top of it. Surface the holder so the
-      # user knows which process to quit (common case: editor/dev tool
-      # squatting 8071) instead of silently failing.
-      holder="$(port_holder "$PORT" 2>/dev/null || true)"
-      msg="[claude-smart] backend: port $PORT held by another process${holder:+ ($holder)}; skipping start"
-      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "$msg"
-      echo "$msg" >&2
-      echo "Free port $PORT (or stop the process above) and run /claude-smart:restart again." >&2
+    if ! claude_smart_service_lock "backend"; then
+      if wait_for_health backend_current_or_compatible 3 1; then
+        embedding_current_or_compatible || log_embedding_degraded
+      fi
+      emit_ok; exit 0
+    fi
+    trap 'claude_smart_service_unlock "backend"' EXIT
+    listener_class="$(classify_backend_listener)"
+    case "$listener_class" in
+      claude_smart)
+        if backend_current_or_compatible; then
+          if ! backend_owned_by_current_vendor; then
+            claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+              "[claude-smart] backend: accepted compatible claude-smart backend on port $PORT from another plugin root; not restarting"
+          fi
+          embedding_current_or_compatible || log_embedding_degraded
+          emit_ok; exit 0
+        fi
+        ;;
+      foreign)
+        holder="$(port_holder "$PORT" 2>/dev/null || true)"
+        msg="[claude-smart] backend: port $PORT held by another process${holder:+ ($holder)}; skipping start"
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "$msg"
+        echo "$msg" >&2
+        echo "Free port $PORT (or stop the process above) and run /claude-smart:restart again." >&2
+        emit_ok; exit 0
+        ;;
+    esac
+    if is_our_backend_running; then
+      embedding_current_or_compatible || log_embedding_degraded
+      emit_ok; exit 0
+    fi
+    if recorded_backend_pid_in_startup_grace; then
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: recorded backend process is still running but not healthy yet; skipping duplicate start"
       emit_ok; exit 0
     fi
+    # Everything above only accepts an existing healthy backend; everything
+    # below stops or replaces one. The bundled-runtime checks sit on that
+    # boundary: if this plugin cannot run its own backend, report that without
+    # tearing down a backend that is currently serving.
     if ! command -v uv >/dev/null 2>&1; then
       if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" != "1" ] && [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
         claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH; starting installer in background"
@@ -293,8 +897,35 @@ case "$CMD" in
         emit_ok; exit 0
       fi
     fi
+    if ! preflight_bundled_reflexio_runtime; then
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: $VENDOR_PREFLIGHT_FAILURE; existing services were not changed"
+      emit_start_failure "$VENDOR_PREFLIGHT_FAILURE"
+      exit 0
+    fi
+    if recorded_backend_pid_alive; then
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: recorded backend process exceeded startup grace without health; restarting"
+      kill_recorded_backend
+      sleep 1
+    fi
+    if stop_stale_backend_listener_if_owned; then
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+        "[claude-smart] backend: existing claude-smart backend is older than plugin $PLUGIN_VERSION; restarting local services"
+    fi
+    stop_stale_embedding_listener_if_owned || true
+    if port_occupied; then
+      # is_our_backend_running already ruled out a healthy Reflexio backend.
+      # Anything still holding the port would make uvicorn fail to bind, so
+      # surface the holder instead of silently starting into a collision.
+      holder="$(port_holder "$PORT" 2>/dev/null || true)"
+      msg="[claude-smart] backend: port $PORT held by another process${holder:+ ($holder)}; skipping start"
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "$msg"
+      echo "$msg" >&2
+      echo "Free port $PORT (or stop the process above) and run /claude-smart:restart again." >&2
+      emit_ok; exit 0
+    fi
     cd "$PLUGIN_ROOT"
-    ensure_vendored_reflexio_active
 
     # Cap local interaction history to keep the SQLite store small for
     # claude-smart users. Reflexio's library defaults are much higher
@@ -318,21 +949,6 @@ case "$CMD" in
     # without touching the file on disk.
     export REFLEXIO_STORAGE="sqlite"
 
-    backend_pythonpath="${PYTHONPATH:-}"
-    if [ -d "$PLUGIN_ROOT/vendor/reflexio/reflexio" ]; then
-      vendor_pythonpath="$PLUGIN_ROOT/vendor/reflexio"
-      pythonpath_sep=":"
-      if claude_smart_is_windows; then
-        # Native Windows Python expects ;-separated Windows-style paths in
-        # PYTHONPATH; MSYS does not auto-convert arbitrary env vars.
-        pythonpath_sep=";"
-        if command -v cygpath >/dev/null 2>&1; then
-          vendor_pythonpath="$(cygpath -w "$vendor_pythonpath")"
-        fi
-      fi
-      backend_pythonpath="$vendor_pythonpath${backend_pythonpath:+$pythonpath_sep$backend_pythonpath}"
-    fi
-
     # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
     # capture so process output cannot grow backend.log past its cap.
     #
@@ -344,28 +960,41 @@ case "$CMD" in
     # CLAUDE_SMART_BACKEND_WORKERS for power users running concurrent
     # Claude Code sessions or wanting zero-downtime recycling.
     workers="${CLAUDE_SMART_BACKEND_WORKERS:-1}"
-    backend_python="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
+    # Sets backend_python / backend_pythonpath for the spawn below. Already run
+    # by the preflight above; repeated here so the spawn does not depend on a
+    # side effect of an earlier, reorderable step.
+    prepare_backend_import_context
+    # Record the spawned pid, not a pgid sampled with ps. On POSIX,
+    # setsid/python os.setsid make this pid the new process group leader;
+    # sampling immediately can race and capture the caller's pgid instead.
+    # On Windows, claude_smart_kill_tree translates the MSYS pid to WINPID.
+    set -- services start --only backend --no-reload --workers "$workers"
     claude_smart_spawn_detached bash "$HERE/backend-log-runner.sh" \
       "$LOG_FILE" "$LOG_MAX_BYTES" -- \
       env PYTHONIOENCODING="${PYTHONIOENCODING:-utf-8}" \
       PYTHONPATH="$backend_pythonpath" \
-      "$backend_python" -m reflexio.cli services start --only backend --no-reload --workers "$workers"
+      CLAUDE_SMART_BACKEND=1 \
+      CLAUDE_SMART_PLUGIN_ROOT="$PLUGIN_ROOT_CANONICAL" \
+      CLAUDE_SMART_VERSION="$PLUGIN_VERSION" \
+      CLAUDE_SMART_REFLEXIO_VENDOR_ROOT="$VENDORED_REFLEXIO_FOR_PYTHON" \
+      "$backend_python" "$HERE/backend-python-runner.py" \
+      --claude-smart-backend=1 \
+      "--claude-smart-plugin-root=$PLUGIN_ROOT_CANONICAL" \
+      "--claude-smart-version=$PLUGIN_VERSION" \
+      "--claude-smart-reflexio-vendor-root=$VENDORED_REFLEXIO_FOR_PYTHON" \
+      -- "$@"
     svc_pid=$!
-    # Record the spawned pid, not a pgid sampled with ps. On POSIX,
-    # setsid/python os.setsid make this pid the new process group leader;
-    # sampling immediately can race and capture the caller's pgid instead.
-    # On Windows, claude_smart_kill_tree translates the MSYS pid to WINPID.
     echo "$svc_pid" > "$PID_FILE"
 
-    # Give uvicorn up to ~10s to answer /health. The very first boot
-    # after a fresh checkout may be slower (LiteLLM import, chromadb
-    # warmup) — dashboard auto-start does the same thing. We always
-    # return ok; the backend catches up in background if it needs to.
-    for _ in 1 2 3 4 5 6 7 8 9 10; do
-      backend_healthy && break
-      sleep 1
-    done
-    if ! backend_healthy; then
+    # Give uvicorn about 20s to answer /health. The first boot after a fresh
+    # checkout may be slower; if it catches up later, the next hook observes it.
+    if wait_for_health backend_owned_by_current_vendor 10 1; then
+      # The Node installer waits 45s for this script. Each curl probe is also
+      # bounded so a wedged listener cannot outlive the caller's timeout budget.
+      if ! wait_for_health embedding_owned_by_current_vendor 5 3; then
+        log_embedding_degraded
+      fi
+    else
       pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
       if [ -n "$pid" ] && ! kill -0 "$pid" 2>/dev/null; then
         reason=$(tail -n 120 "$LOG_FILE" 2>/dev/null | grep -E "No LLM provider available|No generation-capable LLM provider available|CLI not found|skipping provider registration|Application startup failed" | tail -n 1 | sed 's/^[[:space:]]*//')
@@ -391,8 +1020,22 @@ case "$CMD" in
   status)
     if claude_smart_reflexio_url_is_remote; then
       echo "remote configured at $REFLEXIO_URL"
-    elif is_our_backend_running; then
-      echo "running on http://localhost:$PORT"
+    elif backend_owned_by_current_vendor; then
+      if embedding_owned_by_current_vendor; then
+        echo "running on http://localhost:$PORT (bundled Reflexio at $VENDORED_REFLEXIO)"
+      else
+        echo "running on http://localhost:$PORT (bundled Reflexio at $VENDORED_REFLEXIO; embedding degraded on http://127.0.0.1:$EMBEDDING_PORT)"
+      fi
+    elif backend_current_or_compatible; then
+      if embedding_current_or_compatible; then
+        echo "running on http://localhost:$PORT (compatible claude-smart backend)"
+      else
+        echo "running on http://localhost:$PORT (compatible claude-smart backend; embedding degraded on http://127.0.0.1:$EMBEDDING_PORT)"
+      fi
+    elif backend_owned_by_stale_claude_smart; then
+      echo "stale claude-smart backend on http://localhost:$PORT (older than plugin $PLUGIN_VERSION)"
+    elif backend_healthy; then
+      echo "foreign or ambiguous backend on http://localhost:$PORT (not managed by claude-smart)"
     else
       echo "not running"
     fi