claude-smart 0.2.22 → 0.2.24

package/plugin/dashboard/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claude-smart-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3001 -H 127.0.0.1",
+    "build": "next build",
+    "start": "next start -p 3001 -H 127.0.0.1",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.0",
+    "next": "16.2.0",
+    "next-themes": "^0.4.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.0",
+    "shadcn": "^4.0.8",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  }
+}

package/plugin/dashboard/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/plugin/dashboard/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/plugin/hooks/codex-hooks.json

@@ -0,0 +1,67 @@
+{
+  "description": "claude-smart hooks for Codex — learn from sessions via reflexio",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/ensure-plugin-root.sh\" \"$_R\" || true",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/backend-service.sh\" start",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/dashboard-service.sh\" start",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/hook_entry.sh\" codex session-start",
+            "timeout": 30,
+            "statusMessage": "Loading claude-smart context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/hook_entry.sh\" codex user-prompt",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/hook_entry.sh\" codex post-tool",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/plugins/claude-smart\" \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/hook_entry.sh\" codex stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,111 @@
+{
+  "description": "claude-smart hooks — learn from Claude Code sessions via reflexio",
+  "hooks": {
+    "Setup": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/smart-install.sh\"",
+            "timeout": 300
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/ensure-plugin-root.sh\" \"$_R\" || true",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code session-start",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/backend-service.sh\" start",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/dashboard-service.sh\" start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code user-prompt",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code pre-tool",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code post-tool",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code session-end",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/dashboard-service.sh\" session-end",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/backend-service.sh\" session-end",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "claude-smart"
+version = "0.2.24"
+description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "reflexio-ai>=0.2.22",
+    # Used by reflexio's local embedding provider (ONNXMiniLM_L6_V2).
+    # Pulls in onnxruntime + tokenizers; the ~80 MB ONNX model itself is
+    # downloaded on first use, not at install time.
+    "chromadb>=0.5",
+]
+
+[project.scripts]
+claude-smart-hook = "claude_smart.hook:main"
+claude-smart = "claude_smart.cli:main"
+claude-smart-optimizer-assistant = "claude_smart.optimizer_assistant:main"
+
+# NOTE: LOCAL DEV ONLY — do not commit this block to main.
+# Published installs must resolve reflexio-ai from PyPI. This override
+# points at the vendored submodule so editable changes flow through.
+# `git update-index --skip-worktree plugin/pyproject.toml plugin/uv.lock`
+# hides the local divergence from `git status`.
+# [tool.uv.sources]
+# reflexio-ai = { path = "/Users/yilu/repos/claude-smart/reflexio", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claude_smart"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/claude_smart",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["../tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

package/plugin/scripts/_codex_env.sh

@@ -0,0 +1,27 @@
+# Shared bootstrap for Codex hook commands. This file is sourced by hook
+# entries after a tiny root-discovery step, so keep it POSIX-shell compatible.
+
+_HP=$(printenv PATH 2>/dev/null || true)
+if [ -z "$_HP" ] && [ -n "${SHELL:-}" ]; then
+  _HP=$("$SHELL" -lc 'printf %s "$PATH"' 2>/dev/null || true)
+fi
+_HP=$(printf '%s' "$_HP" | tr ' ' ':')
+export PATH="${_HP:+$_HP:}$PATH"
+
+if [ -z "${_R:-}" ]; then
+  _R="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}"
+fi
+if [ -z "$_R" ]; then
+  _R=$(ls -dt "$HOME/plugins/claude-smart" \
+    "$HOME/.codex/plugins/cache/reflexioai/claude-smart"/*/ \
+    2>/dev/null | head -n 1)
+fi
+if [ -z "$_R" ]; then
+  echo "claude-smart: plugin root not found" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+_R="${_R%/}"
+export _R
+export PLUGIN_ROOT="$_R"
+export CLAUDE_PLUGIN_ROOT="$_R"

package/plugin/scripts/_lib.sh

@@ -0,0 +1,325 @@
+# Shared helpers for claude-smart plugin scripts. Source, do not execute.
+
+# Claude Code hooks run with a minimal non-interactive PATH that often omits
+# nvm/asdf/brew shims where `npm`, `uv`, etc. live. Pull the user's login-shell
+# PATH the same way claude-mem does so hook-spawned scripts find them without
+# the user having to mutate their global PATH. Best-effort — failures silent.
+claude_smart_source_login_path() {
+  local _SHELL_PATH
+  if [ -n "${SHELL:-}" ] && [ -x "$SHELL" ]; then
+    if _SHELL_PATH="$("$SHELL" -lc 'printf %s "$PATH"' 2>/dev/null)"; then
+      [ -n "$_SHELL_PATH" ] && export PATH="$_SHELL_PATH:$PATH"
+    fi
+  fi
+}
+
+# Prepend the astral.sh installer's default bin directories to PATH so a
+# freshly-installed `uv` is reachable before the user re-sources their
+# shell rc. Prepend (not append) so the just-installed binary wins over
+# any stale copy earlier in PATH. Literals only — no subshell, so safe
+# under `set -u`.
+claude_smart_prepend_astral_bins() {
+  export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
+}
+
+# Prepend claude-smart's private Node.js install, if present. The Setup
+# hook installs Node here when the user does not already have a suitable
+# node/npm on PATH, so later hook-spawned dashboard scripts can run without
+# requiring nvm/brew/global npm to be visible from Claude Code's shell.
+claude_smart_prepend_node_bins() {
+  local _CS_NODE_ROOT
+  _CS_NODE_ROOT="$HOME/.claude-smart/node/current"
+  export PATH="$_CS_NODE_ROOT/bin:$_CS_NODE_ROOT:$PATH"
+}
+
+claude_smart_dashboard_unavailable_marker() {
+  printf '%s\n' "$HOME/.claude-smart/dashboard-unavailable"
+}
+
+claude_smart_node_recovery_hint() {
+  cat <<'EOF'
+Recovery:
+  1. Restart Claude Code to let claude-smart retry its private Node.js install.
+  2. If the retry is blocked by your network or OS policy, install Node.js 20.9+ manually:
+EOF
+  if claude_smart_is_windows; then
+    cat <<'EOF'
+     - winget install OpenJS.NodeJS.LTS
+     - or download the LTS installer from https://nodejs.org/
+EOF
+  elif [ "$(uname -s 2>/dev/null)" = "Darwin" ]; then
+    cat <<'EOF'
+     - brew install node
+     - or download the LTS installer from https://nodejs.org/
+EOF
+  else
+    cat <<'EOF'
+     - use your distro package manager for nodejs/npm
+     - or download the LTS archive from https://nodejs.org/
+EOF
+  fi
+  cat <<'EOF'
+  3. Run /claude-smart:restart, then /claude-smart:dashboard.
+EOF
+}
+
+claude_smart_write_dashboard_unavailable() {
+  local reason marker
+  reason="$1"
+  marker="$(claude_smart_dashboard_unavailable_marker)"
+  mkdir -p "$(dirname "$marker")"
+  {
+    printf 'claude-smart dashboard is unavailable: %s\n\n' "$reason"
+    printf 'The learning backend and hooks can still work; only the dashboard UI is affected.\n\n'
+    printf 'Private Node.js location: %s\n\n' "$HOME/.claude-smart/node/current"
+    claude_smart_node_recovery_hint
+  } > "$marker"
+}
+
+claude_smart_clear_dashboard_unavailable() {
+  rm -f "$(claude_smart_dashboard_unavailable_marker)"
+}
+
+# Return 0 (true) if running under a Windows-flavoured bash (Git Bash,
+# MSYS, Cygwin). Used to gate POSIX-only primitives (setsid, process
+# groups) and route around Windows-specific potholes (the python3 App
+# Execution Alias stub at WindowsApps\python3.exe).
+claude_smart_is_windows() {
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Print the absolute path of a working python interpreter, or nothing
+# (and return non-zero) if none is usable. On Windows, `python3` is
+# usually the Microsoft Store "App Execution Alias" stub at
+# %LocalAppData%\Microsoft\WindowsApps\python3.exe — `command -v python3`
+# returns truthy but invoking it just prints a "Python was not found"
+# message and exits non-zero. We probe with `-V` to filter the stub out
+# and prefer `python` (the real interpreter when one is installed).
+claude_smart_resolve_python() {
+  if claude_smart_is_windows; then
+    for cand in python python3; do
+      if command -v "$cand" >/dev/null 2>&1 && "$cand" -V >/dev/null 2>&1; then
+        command -v "$cand"
+        return 0
+      fi
+    done
+    return 1
+  fi
+  for cand in python3 python; do
+    if command -v "$cand" >/dev/null 2>&1 && "$cand" -V >/dev/null 2>&1; then
+      command -v "$cand"
+      return 0
+    fi
+  done
+  return 1
+}
+
+claude_smart_download() {
+  local url dest src _CS_PY
+  url="$1"
+  dest="$2"
+  mkdir -p "$(dirname "$dest")"
+  case "$url" in
+    file://*)
+      src="${url#file://}"
+      cp "$src" "$dest"
+      return $?
+      ;;
+  esac
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$url" -o "$dest"
+    return $?
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget -q -O "$dest" "$url"
+    return $?
+  fi
+  if command -v powershell >/dev/null 2>&1; then
+    URL="$url" DEST="$dest" powershell -NoProfile -ExecutionPolicy Bypass -Command \
+      '$ProgressPreference="SilentlyContinue"; Invoke-WebRequest -Uri $env:URL -OutFile $env:DEST'
+    return $?
+  fi
+  if command -v pwsh >/dev/null 2>&1; then
+    URL="$url" DEST="$dest" pwsh -NoProfile -Command \
+      '$ProgressPreference="SilentlyContinue"; Invoke-WebRequest -Uri $env:URL -OutFile $env:DEST'
+    return $?
+  fi
+  _CS_PY=$(claude_smart_resolve_python || true)
+  if [ -n "$_CS_PY" ]; then
+    "$_CS_PY" - "$url" "$dest" <<'PY'
+import sys
+import urllib.request
+
+url, dest = sys.argv[1], sys.argv[2]
+with urllib.request.urlopen(url, timeout=60) as response:
+    data = response.read()
+with open(dest, "wb") as fh:
+    fh.write(data)
+PY
+    return $?
+  fi
+  return 1
+}
+
+claude_smart_sha256_file() {
+  local path _CS_PY
+  path="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$path" | awk '{print $1}'
+    return ${PIPESTATUS[0]}
+  fi
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$path" | awk '{print $1}'
+    return ${PIPESTATUS[0]}
+  fi
+  if command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$path" | awk '{print $NF}'
+    return ${PIPESTATUS[0]}
+  fi
+  _CS_PY=$(claude_smart_resolve_python || true)
+  if [ -n "$_CS_PY" ]; then
+    "$_CS_PY" - "$path" <<'PY'
+import hashlib
+import sys
+
+h = hashlib.sha256()
+with open(sys.argv[1], "rb") as fh:
+    for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+        h.update(chunk)
+print(h.hexdigest())
+PY
+    return $?
+  fi
+  return 1
+}
+
+# Return 0 if `node` exists and satisfies the minimum major/minor pair.
+# Patch versions are intentionally ignored because our requirement is a
+# floor, not an exact runtime pin.
+claude_smart_node_satisfies() {
+  local min_major min_minor version major minor
+  min_major="$1"
+  min_minor="$2"
+  command -v node >/dev/null 2>&1 || return 1
+  version=$(node -v 2>/dev/null | sed 's/^v//') || return 1
+  major=$(printf '%s' "$version" | awk -F. '{print $1}')
+  minor=$(printf '%s' "$version" | awk -F. '{print $2}')
+  [ -n "$major" ] && [ -n "$minor" ] || return 1
+  case "$major:$minor" in
+    *[!0-9:]*|:*|*:) return 1 ;;
+  esac
+  [ "$major" -gt "$min_major" ] && return 0
+  [ "$major" -eq "$min_major" ] && [ "$minor" -ge "$min_minor" ]
+}
+
+claude_smart_resolve_npm() {
+  local cand
+  for cand in npm npm.cmd; do
+    if command -v "$cand" >/dev/null 2>&1; then
+      command -v "$cand"
+      return 0
+    fi
+  done
+  return 1
+}
+
+claude_smart_npm_available() {
+  local npm_bin
+  npm_bin=$(claude_smart_resolve_npm || true)
+  [ -n "$npm_bin" ] || return 1
+  "$npm_bin" --version >/dev/null 2>&1
+}
+
+# Spawn a command fully detached from the current shell so a hook timeout
+# (Claude Code's install/SessionStart budget) cannot kill it mid-flight.
+# POSIX: setsid → python3 os.setsid → nohup (in that order of strength).
+# Windows: nohup alone — Git Bash has no setsid, no process groups, and
+# `os.setsid()` is POSIX-only; nohup ignores SIGHUP which is enough to
+# survive the parent console closing. The python3 fallback is gated on a
+# real-interpreter probe (-V) so the Windows App Execution Alias stub
+# doesn't get invoked. Caller is responsible for redirecting stdout/stderr;
+# we do not impose a log destination here. Stdin is closed so the child
+# cannot inherit a tty. Use `$!` after this call to capture the pid.
+claude_smart_spawn_detached() {
+  if claude_smart_is_windows; then
+    nohup "$@" < /dev/null &
+    return 0
+  fi
+  if command -v setsid >/dev/null 2>&1; then
+    setsid nohup "$@" < /dev/null &
+  elif _CS_PY=$(claude_smart_resolve_python) && [ -n "$_CS_PY" ]; then
+    "$_CS_PY" -c 'import os,sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])' \
+      "$@" < /dev/null &
+  else
+    nohup "$@" < /dev/null &
+  fi
+}
+
+# Terminate a process and (on POSIX) its whole process group, escalating
+# from TERM to KILL after a short grace period. On Windows there are no
+# POSIX process groups, so we use `taskkill /T /F /PID` which walks the
+# child-process tree via the Windows job-object/parent-pid relationships
+# — the closest equivalent to a group kill.
+#
+# Windows-specific subtlety: in Git Bash / MSYS, `$!` for a backgrounded
+# job returns the MSYS pid (an internal counter), NOT the native Windows
+# pid that taskkill needs. `ps -W` (or `-o winpid=`) exposes the WINPID
+# column for the translation. If the lookup fails we fall back to
+# treating the input as a native pid, so callers can pass either an MSYS
+# pid (recorded via $!) or a Windows pid (from tasklist) interchangeably.
+# The `//T //F //PID` syntax escapes Git Bash's MSYS path-mangling of
+# arguments that begin with `/`.
+claude_smart_kill_tree() {
+  pid="$1"
+  [ -z "$pid" ] && return 0
+  if claude_smart_is_windows; then
+    # Git Bash's `ps` is the procps fork, not BSD/Linux ps; it has no
+    # -o option but its default header is `PID PPID PGID WINPID TTY ...`,
+    # so column 4 of the data row is the Windows pid. awk extracts it
+    # without depending on -o support.
+    target=""
+    if command -v ps >/dev/null 2>&1; then
+      target=$(ps -p "$pid" 2>/dev/null | awk 'NR==2 {print $4}' | tr -d ' \r\n' || true)
+    fi
+    [ -z "$target" ] && target="$pid"
+    if command -v taskkill >/dev/null 2>&1; then
+      taskkill //T //F //PID "$target" >/dev/null 2>&1 || true
+    else
+      kill -TERM "$pid" 2>/dev/null || true
+      sleep 0.5
+      kill -KILL "$pid" 2>/dev/null || true
+    fi
+    return 0
+  fi
+  current_pgid=""
+  if command -v ps >/dev/null 2>&1; then
+    current_pgid=$(ps -o pgid= -p "$$" 2>/dev/null | tr -d ' ')
+  fi
+  if [ -n "$current_pgid" ] && [ "$pid" = "$current_pgid" ]; then
+    return 0
+  fi
+  if ! kill -TERM -- "-$pid" 2>/dev/null; then
+    kill -TERM "$pid" 2>/dev/null || true
+    sleep 0.5
+    kill -KILL "$pid" 2>/dev/null || true
+    return 0
+  fi
+  for _ in 1 2 3 4 5; do
+    kill -0 -- "-$pid" 2>/dev/null || return 0
+    sleep 0.2
+  done
+  kill -KILL -- "-$pid" 2>/dev/null || true
+}
+
+# Return 0 (true) if $1 names a pid file whose pid is currently alive.
+# Silent on missing/empty/stale files.
+claude_smart_pid_alive_file() {
+  pid_file="$1"
+  [ -f "$pid_file" ] || return 1
+  pid=$(cat "$pid_file" 2>/dev/null || echo "")
+  [ -n "$pid" ] || return 1
+  kill -0 "$pid" 2>/dev/null
+}