claude-smart 0.2.23 → 0.2.25

package/plugin/scripts/backend-service.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# Auto-start the reflexio FastAPI backend (port 8071) if it's not already
+# running. Mirrors dashboard-service.sh: detached spawn, returns immediately
+# so the SessionStart hook doesn't block the session.
+#
+# Subcommands:
+#   start         probe /health; if nothing we recognize is on the port,
+#                 spawn `uv run reflexio services start --only backend
+#                 --no-reload` detached. Polls /health briefly so first
+#                 use after session start lands on a warm server, then
+#                 returns a continue payload regardless.
+#   stop          SIGTERM the recorded process group, escalating to
+#                 SIGKILL after a short grace period.
+#   session-end   no-op by default; only stops the backend if
+#                 CLAUDE_SMART_BACKEND_STOP_ON_END=1 (opt-in — the
+#                 backend is intended to be long-lived across sessions).
+#   status        print "running on http://localhost:PORT" or "not running".
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+claude_smart_source_login_path
+claude_smart_prepend_astral_bins
+
+CMD="${1:-start}"
+PORT=8071
+# Pass through to `reflexio services start/stop` so the spawned backend
+# binds to PORT instead of reflexio's library default (8081).
+export BACKEND_PORT="$PORT"
+
+# Default: route extraction through the local claude CLI + ONNX embedder
+# so claude-smart works without any LLM API key. Users can opt out by
+# pre-exporting these to 0.
+export CLAUDE_SMART_USE_LOCAL_CLI="${CLAUDE_SMART_USE_LOCAL_CLI:-1}"
+export CLAUDE_SMART_USE_LOCAL_EMBEDDING="${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-1}"
+# The backend can be spawned from contexts whose PATH lacks the claude
+# CLI dir (commonly ~/.local/bin or /opt/homebrew/bin). Pin the CLI
+# explicitly if we can resolve it from our own (post-login-path) PATH.
+if [ -z "${CLAUDE_SMART_CLI_PATH:-}" ]; then
+  if _cs_claude_path=$(command -v claude 2>/dev/null) && [ -n "$_cs_claude_path" ]; then
+    export CLAUDE_SMART_CLI_PATH="$_cs_claude_path"
+  elif [ -x "$HOME/.local/bin/claude" ]; then
+    export CLAUDE_SMART_CLI_PATH="$HOME/.local/bin/claude"
+  fi
+  unset _cs_claude_path
+fi
+
+PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+
+STATE_DIR="$HOME/.claude-smart"
+PID_FILE="$STATE_DIR/backend.pid"
+LOG_FILE="$STATE_DIR/backend.log"
+mkdir -p "$STATE_DIR"
+
+emit_ok() { echo '{"continue":true,"suppressOutput":true}'; }
+
+# Tree-kill the recorded process. Delegates to claude_smart_kill_tree
+# (POSIX: signal the process group; Windows: taskkill /T /F /PID).
+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.
+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
+}
+
+# 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.
+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
+    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
+  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
+}
+
+# Reap any reflexio/uvicorn listener still holding $PORT after the PID
+# file kill. Filters by cmdline so we don't knock over an unrelated
+# service a user has bound to 8071 — symmetric with start's refusal to
+# stomp on a foreign listener. Silent on failure.
+reap_port_listeners() {
+  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)
+    case "$cmdline" in
+      *reflexio*|*uvicorn*) ours="$ours $pid" ;;
+    esac
+  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"
+  done
+  [ -z "$remaining" ] && return 0
+  # shellcheck disable=SC2086
+  kill -KILL $remaining 2>/dev/null || true
+}
+
+# Full shutdown: kill the recorded process group (if any) then sweep the
+# 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.
+full_stop() {
+  if [ -f "$PID_FILE" ]; then
+    kill_group "$(cat "$PID_FILE" 2>/dev/null)"
+    rm -f "$PID_FILE"
+  fi
+  reap_port_listeners
+}
+
+case "$CMD" in
+  start)
+    # Opt-out: users who don't want the backend managed by the hook can
+    # set CLAUDE_SMART_BACKEND_AUTOSTART=0.
+    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.
+      echo "[claude-smart] backend: port $PORT held by another process; skipping" >>"$LOG_FILE"
+      emit_ok; exit 0
+    fi
+    if ! command -v uv >/dev/null 2>&1; then
+      echo "[claude-smart] backend: uv not on PATH; skipping" >>"$LOG_FILE"
+      emit_ok; exit 0
+    fi
+    cd "$PLUGIN_ROOT"
+
+    # Cap local interaction history to keep the SQLite store small for
+    # claude-smart users. Reflexio's library defaults are much higher
+    # (250k/50k) for server deployments; here we override only in the
+    # claude-smart plugin context. Users can still override via env.
+    export INTERACTION_CLEANUP_THRESHOLD="${INTERACTION_CLEANUP_THRESHOLD:-500}"
+    export INTERACTION_CLEANUP_DELETE_COUNT="${INTERACTION_CLEANUP_DELETE_COUNT:-200}"
+
+    # --no-reload: uvicorn's reloader forks a supervisor; makes
+    # bookkeeping harder and we don't need hot-reload for a user-facing
+    # service. Detach via claude_smart_spawn_detached so the same code
+    # path covers Linux (setsid), macOS (python3 os.setsid), and Windows
+    # (nohup; no process groups). Caller-side stdout/stderr redirection
+    # works across all three primitives — Git Bash routes the > and 2>&1
+    # through to the underlying CRT before nohup execs the child.
+    claude_smart_spawn_detached uv run --project "$PLUGIN_ROOT" --quiet \
+      reflexio services start --only backend --no-reload \
+      >>"$LOG_FILE" 2>&1
+    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
+    emit_ok
+    ;;
+  stop)
+    full_stop
+    emit_ok
+    ;;
+  session-end)
+    # Default: leave the backend running so learning keeps flowing
+    # between sessions. Opt in to teardown with
+    # CLAUDE_SMART_BACKEND_STOP_ON_END=1.
+    if [ "${CLAUDE_SMART_BACKEND_STOP_ON_END:-0}" = "1" ]; then
+      full_stop
+    fi
+    emit_ok
+    ;;
+  status)
+    if is_our_backend_running; then echo "running on http://localhost:$PORT"; else echo "not running"; fi
+    ;;
+  *)
+    emit_ok
+    ;;
+esac

package/plugin/scripts/cli.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Wrapper for slash commands that invoke the claude_smart CLI via uv.
+# Claude Code runs `!` bash directives in slash command .md files in a
+# non-interactive, non-login shell that does NOT source ~/.zshrc or
+# ~/.bash_profile. As a result, binaries installed by smart-install.sh
+# at ~/.local/bin (e.g. uv from the astral.sh installer) are invisible
+# to those directives until the user manually re-sources their shell rc.
+# This wrapper bootstraps PATH the same way hook_entry.sh does so the
+# slash commands work on a fresh install.
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+claude_smart_source_login_path
+claude_smart_prepend_astral_bins
+claude_smart_prepend_node_bins
+
+PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+
+# If the Setup hook recorded an install failure, surface that reason
+# instead of falling through to a generic "uv not found" — mirrors the
+# branch at hook_entry.sh so slash commands and hooks behave consistently
+# on a broken install.
+FAILURE_MARKER="$HOME/.claude-smart/install-failed"
+if [ -f "$FAILURE_MARKER" ]; then
+  msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "")"
+  [ -n "$msg" ] || msg="unknown error"
+  echo "claude-smart is not installed correctly: $msg" >&2
+  echo "Re-run the plugin's Setup (restart Claude Code) or fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
+  exit 1
+fi
+
+if ! command -v uv >/dev/null 2>&1; then
+  echo "claude-smart: 'uv' not found on PATH." >&2
+  echo "Install it from https://docs.astral.sh/uv/ or restart Claude Code so the Setup hook can install it." >&2
+  exit 1
+fi
+
+exec uv run --project "$PLUGIN_ROOT" --quiet python -m claude_smart.cli "$@"

package/plugin/scripts/dashboard-build.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Build the Next.js dashboard ($PLUGIN_ROOT/dashboard) in two steps:
+#   1. npm ci (skipped if node_modules exists and is newer than package.json
+#      and package-lock.json)
+#   2. npm run build (skipped if .next exists and is newer than
+#      package.json)
+#
+# Designed to run detached from any hook so the multi-minute first-run
+# cost never trips Claude Code's hook timeout. dashboard-service.sh
+# spawns this on first SessionStart when .next is missing; the user can
+# also invoke it manually for recovery.
+#
+# Concurrency: a build-pid file at $STATE_DIR/dashboard-build.pid is
+# used to mark "build in progress" so dashboard-open.sh can surface a
+# "still building, retry in ~1 minute" message instead of the generic
+# .next-missing error. The pid file is removed on exit (success, fail,
+# or interrupt).
+#
+# Partial-build safety: an INT/TERM trap wipes any half-written .next
+# so dashboard-service.sh's "no .next → start build" probe stays honest.
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+claude_smart_source_login_path
+claude_smart_prepend_node_bins
+
+PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+DASHBOARD_DIR="$PLUGIN_ROOT/dashboard"
+
+STATE_DIR="$HOME/.claude-smart"
+LOG_FILE="$STATE_DIR/dashboard.log"
+BUILD_PID_FILE="$STATE_DIR/dashboard-build.pid"
+BUILD_LOCK_DIR="$STATE_DIR/dashboard-build.lock"
+mkdir -p "$STATE_DIR"
+
+log() { printf '[claude-smart] %s\n' "$1" >>"$LOG_FILE"; }
+
+if [ ! -d "$DASHBOARD_DIR" ]; then
+  log "dashboard build: no $DASHBOARD_DIR; nothing to do"
+  exit 0
+fi
+NPM_BIN=$(claude_smart_resolve_npm || true)
+if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
+  reason="npm is not on PATH; dashboard dependencies cannot be installed"
+  log "dashboard build: $reason"
+  claude_smart_write_dashboard_unavailable "$reason"
+  exit 1
+fi
+
+# Atomic single-flight: mkdir is a single atomic syscall, so two concurrent
+# builds (e.g., smart-install.sh and a SessionStart-driven dashboard-service.sh
+# firing within milliseconds on first install) cannot both pass this check.
+# BUILD_PID_FILE remains as status metadata for dashboard-open.sh and
+# dashboard-service.sh to probe — it is written only after the lock is held
+# and removed only by the lock holder.
+if ! mkdir "$BUILD_LOCK_DIR" 2>/dev/null; then
+  if claude_smart_pid_alive_file "$BUILD_PID_FILE"; then
+    log "dashboard build: already in progress; skipping"
+    exit 0
+  fi
+  # Stale lock from a crashed build (lock dir survived but owner is gone).
+  # Reclaim it; if another process beats us to the reclaim, defer to them.
+  rm -rf "$BUILD_LOCK_DIR"
+  rm -f "$BUILD_PID_FILE"
+  if ! mkdir "$BUILD_LOCK_DIR" 2>/dev/null; then
+    log "dashboard build: lost race for stale lock; skipping"
+    exit 0
+  fi
+fi
+echo $$ > "$BUILD_PID_FILE"
+
+release_lock() {
+  rm -f "$BUILD_PID_FILE"
+  rmdir "$BUILD_LOCK_DIR" 2>/dev/null || rm -rf "$BUILD_LOCK_DIR"
+}
+cleanup() {
+  status=$?
+  release_lock
+  exit "${status:-0}"
+}
+on_interrupt() {
+  rm -rf "$DASHBOARD_DIR/.next"
+  rm -rf "$DASHBOARD_DIR/node_modules"
+  release_lock
+  log "dashboard build: interrupted; removed partial .next and node_modules"
+  exit 130
+}
+trap cleanup EXIT
+trap on_interrupt INT TERM
+
+cd "$DASHBOARD_DIR"
+
+# Cheap freshness check: skip reinstall when node_modules is newer than
+# package.json and package-lock.json. Avoids re-downloading the dep tree
+# on every SessionStart while still picking up version bumps when the
+# plugin updates.
+needs_install=1
+if [ -d node_modules ] && [ node_modules -nt package.json ]; then
+  if [ ! -f package-lock.json ] || [ node_modules -nt package-lock.json ]; then
+    needs_install=0
+  fi
+fi
+if [ "$needs_install" = "1" ]; then
+  if [ -f package-lock.json ]; then
+    install_cmd="ci"
+  else
+    install_cmd="install"
+  fi
+  log "dashboard build: running npm $install_cmd..."
+  if ! "$NPM_BIN" "$install_cmd" --silent --no-fund --no-audit >>"$LOG_FILE" 2>&1; then
+    rm -rf "$DASHBOARD_DIR/node_modules"
+    reason="npm $install_cmd failed; removed partial node_modules; see $LOG_FILE"
+    log "dashboard build: $reason"
+    claude_smart_write_dashboard_unavailable "$reason"
+    exit 1
+  fi
+fi
+
+needs_build=1
+if [ -d .next ] && [ .next -nt package.json ]; then
+  needs_build=0
+fi
+if [ "$needs_build" = "1" ]; then
+  log "dashboard build: running next build (this can take 1-2 min)..."
+  if ! "$NPM_BIN" run build >>"$LOG_FILE" 2>&1; then
+    rm -rf "$DASHBOARD_DIR/.next"
+    reason="next build failed; see $LOG_FILE"
+    log "dashboard build: $reason"
+    claude_smart_write_dashboard_unavailable "$reason"
+    exit 1
+  fi
+  claude_smart_clear_dashboard_unavailable
+  log "dashboard build: complete"
+else
+  claude_smart_clear_dashboard_unavailable
+  log "dashboard build: .next is up-to-date; skipping"
+fi

package/plugin/scripts/dashboard-open.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Start backend + dashboard (idempotent), wait briefly for dashboard to come
+# up, print statuses, then open http://localhost:3001 in the default browser.
+#
+# Exists so the /claude-smart:dashboard slash command can invoke a single
+# plain `bash <script>` with no inline $(...) or ${...:-...} expansion in
+# the command string — Claude Code's permission checker rejects those.
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SCRIPTS="$HERE"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+claude_smart_source_login_path
+claude_smart_prepend_node_bins
+
+STATE_DIR="$HOME/.claude-smart"
+BACKEND_LOG="$STATE_DIR/backend.log"
+DASHBOARD_LOG="$STATE_DIR/dashboard.log"
+DASHBOARD_UNAVAILABLE="$(claude_smart_dashboard_unavailable_marker)"
+
+# Capture start-command output so we can surface fatal errors (e.g. uv/npm
+# missing, port collisions, .next not built) rather than silently swallow
+# them. The service scripts themselves write to their own log files on
+# successful detached spawn, so stdout/stderr here are normally empty.
+backend_start_out=$(bash "$SCRIPTS/backend-service.sh" start 2>&1) || true
+dashboard_start_out=$(bash "$SCRIPTS/dashboard-service.sh" start 2>&1) || true
+
+# Poll both services for up to ~10s so a cold boot has time to come up.
+backend_status="not running"
+dashboard_status="not running"
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+    backend_status=$(bash "$SCRIPTS/backend-service.sh" status)
+    dashboard_status=$(bash "$SCRIPTS/dashboard-service.sh" status)
+    if [ "$backend_status" != "not running" ] && [ "$dashboard_status" != "not running" ]; then
+        break
+    fi
+    sleep 1
+done
+
+echo "backend:   $backend_status"
+echo "dashboard: $dashboard_status"
+
+# Print any "skipping" diagnostic the service scripts appended to their
+# logs (uv/npm missing, port held, .next missing, etc.). Tail is cheap
+# and gives the user something actionable instead of just "not running".
+show_log_tail() {
+    label="$1"
+    log_path="$2"
+    if [ -f "$log_path" ]; then
+        tail=$(tail -n 20 "$log_path" 2>/dev/null || true)
+        if [ -n "$tail" ]; then
+            echo ""
+            echo "--- $label log (last 20 lines: $log_path) ---"
+            echo "$tail"
+        fi
+    else
+        echo ""
+        echo "[$label] no log at $log_path"
+    fi
+}
+
+failed=0
+if [ "$backend_status" = "not running" ]; then
+    failed=1
+    echo ""
+    echo "ERROR: backend failed to start on http://localhost:8071"
+    [ -n "$backend_start_out" ] && echo "$backend_start_out"
+    show_log_tail "backend" "$BACKEND_LOG"
+fi
+if [ "$dashboard_status" = "not running" ]; then
+    failed=1
+    echo ""
+    BUILD_PID_FILE="$STATE_DIR/dashboard-build.pid"
+    if claude_smart_pid_alive_file "$BUILD_PID_FILE"; then
+        echo "dashboard: still building (first-run cost, ~1-2 min). Re-run /claude-smart:dashboard in a minute."
+    else
+        echo "ERROR: dashboard failed to start on http://localhost:3001"
+        [ -n "$dashboard_start_out" ] && echo "$dashboard_start_out"
+        if [ -f "$DASHBOARD_UNAVAILABLE" ]; then
+            echo ""
+            echo "--- dashboard availability ($DASHBOARD_UNAVAILABLE) ---"
+            cat "$DASHBOARD_UNAVAILABLE" 2>/dev/null || true
+        fi
+        show_log_tail "dashboard" "$DASHBOARD_LOG"
+    fi
+fi
+
+if [ "$failed" = "1" ]; then
+    echo ""
+    echo "Not opening the browser because one or more services failed to start."
+    exit 1
+fi
+
+URL="http://localhost:3001"
+PY_BIN=$(claude_smart_resolve_python || true)
+if [ -n "$PY_BIN" ] && "$PY_BIN" -m webbrowser "$URL"; then
+    echo "Opened $URL"
+elif command -v open >/dev/null 2>&1 && open "$URL"; then
+    echo "Opened $URL"
+elif command -v xdg-open >/dev/null 2>&1 && xdg-open "$URL"; then
+    echo "Opened $URL"
+elif command -v powershell >/dev/null 2>&1 && powershell -NoProfile -Command "Start-Process '$URL'"; then
+    echo "Opened $URL"
+else
+    echo "Dashboard is running at $URL"
+fi

package/plugin/scripts/dashboard-service.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# Auto-start the claude-smart Next.js dashboard (port 3001) if it's not
+# already running. Mirrors how claude-mem boots its worker on SessionStart:
+# detached, returns immediately so the hook doesn't block the session.
+#
+# Subcommands:
+#   start         probe the port; spawn `npm run start` if our dashboard
+#                 isn't already answering. Never builds in foreground — if
+#                 .next is missing, logs and bails (Setup is responsible for
+#                 the build; rerun it or restart Claude Code to retry).
+#   stop          kill the recorded process group, and (if our dashboard
+#                 is still responding on the port) kill the port listener
+#                 as a fallback — covers dashboards started outside this
+#                 script or whose PGID signalling missed
+#   session-end   no-op by default; stops the dashboard if
+#                 CLAUDE_SMART_DASHBOARD_STOP_ON_END=1 (opt-in — the dashboard
+#                 is intended to be long-lived across sessions)
+#   status        print "running on http://localhost:PORT" or "not running"
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+claude_smart_source_login_path
+claude_smart_prepend_node_bins
+
+CMD="${1:-start}"
+PORT=3001
+
+PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+DASHBOARD_DIR="$PLUGIN_ROOT/dashboard"
+WORKSPACE_CWD="${PWD:-}"
+
+STATE_DIR="$HOME/.claude-smart"
+PID_FILE="$STATE_DIR/dashboard.pid"
+LOG_FILE="$STATE_DIR/dashboard.log"
+mkdir -p "$STATE_DIR"
+
+emit_ok() { echo '{"continue":true,"suppressOutput":true}'; }
+
+# Tree-kill the recorded process. Delegates to claude_smart_kill_tree
+# (POSIX: signal the process group; Windows: taskkill /T /F /PID).
+kill_group() {
+  claude_smart_kill_tree "$1"
+}
+
+# True if the marker header served by app/api/health is present on the
+# port. Requires curl — absence is reported as false.
+marker_responds() {
+  command -v curl >/dev/null 2>&1 || return 1
+  curl -sfI "http://127.0.0.1:$PORT/api/health" 2>/dev/null \
+    | grep -qi '^x-claude-smart-dashboard:'
+}
+
+# True only if *our* dashboard is on the port. Uses the marker header so a
+# foreign listener on 3001 doesn't cause us to silently skip starting.
+is_our_dashboard_running() {
+  if [ -f "$PID_FILE" ]; then
+    pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      # PID alive — still verify the port responds with our marker so we
+      # don't claim "running" when the server crashed but the group leader
+      # lingered.
+      if command -v curl >/dev/null 2>&1; then
+        marker_responds && return 0
+      else
+        # No curl — fall back to PID liveness alone.
+        return 0
+      fi
+    fi
+  fi
+  # No PID or dead PID — probe the port for our marker (recovers after a
+  # stale PID file from a crash).
+  marker_responds && return 0
+  return 1
+}
+
+# True if *something* is listening on the port, regardless of marker.
+port_occupied() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -sf -o /dev/null "http://127.0.0.1:$PORT" 2>/dev/null && return 0
+    # curl with -sfI against a 404/405 still indicates "something answered".
+    # Use a connect-only probe as a secondary signal.
+  fi
+  (echo >"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null
+}
+
+case "$CMD" in
+  start)
+    # Opt-out: users who don't want the dashboard long-lived can set
+    # CLAUDE_SMART_DASHBOARD_AUTOSTART=0 in their environment.
+    if [ "${CLAUDE_SMART_DASHBOARD_AUTOSTART:-1}" = "0" ]; then
+      emit_ok; exit 0
+    fi
+    if [ ! -d "$DASHBOARD_DIR" ]; then emit_ok; exit 0; fi
+    if is_our_dashboard_running; then claude_smart_clear_dashboard_unavailable; emit_ok; exit 0; fi
+    if port_occupied; then
+      echo "[claude-smart] dashboard: port $PORT held by another process; skipping" >>"$LOG_FILE"
+      emit_ok; exit 0
+    fi
+    NPM_BIN=$(claude_smart_resolve_npm || true)
+    if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
+      reason="npm is not on PATH; dashboard cannot start"
+      echo "[claude-smart] dashboard: $reason; skipping" >>"$LOG_FILE"
+      claude_smart_write_dashboard_unavailable "$reason"
+      emit_ok; exit 0
+    fi
+
+    # `npm run start` requires a prior `next build`. Do NOT build in the
+    # foreground here — SessionStart hooks have a tight timeout and a cold
+    # Next build easily exceeds it. If .next is missing, spawn a detached
+    # build (dashboard-build.sh) so the first-install cost is paid out of
+    # band. dashboard-open.sh detects the build-pid file to surface a
+    # "still building" message instead of a generic error.
+    if [ ! -d "$DASHBOARD_DIR/.next" ]; then
+      BUILD_PID_FILE="$STATE_DIR/dashboard-build.pid"
+      if ! claude_smart_pid_alive_file "$BUILD_PID_FILE"; then
+        echo "[claude-smart] dashboard: .next missing — starting background build (~1-2 min)" >>"$LOG_FILE"
+        claude_smart_spawn_detached bash "$HERE/dashboard-build.sh" >>"$LOG_FILE" 2>&1
+      fi
+      emit_ok; exit 0
+    fi
+
+    cd "$DASHBOARD_DIR"
+
+    # Detach so the hook returns immediately. claude_smart_spawn_detached
+    # picks the strongest primitive available:
+    #   - Linux: setsid (puts child in its own session/group, pid==pgid).
+    #   - macOS: python3 os.setsid + execvp (same effect as setsid).
+    #   - Windows: nohup alone (no process groups; tree-kill via taskkill).
+    # Caller-side `>>file 2>&1` redirection is honoured before the child
+    # detaches, so per-OS log paths stay identical.
+    export CLAUDE_SMART_DASHBOARD_WORKSPACE="$WORKSPACE_CWD"
+    claude_smart_spawn_detached "$NPM_BIN" run start >>"$LOG_FILE" 2>&1
+    dash_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 "$dash_pid" > "$PID_FILE"
+    dashboard_ready=0
+    for _ in 1 2 3 4 5; do
+      if marker_responds; then
+        dashboard_ready=1
+        claude_smart_clear_dashboard_unavailable
+        break
+      fi
+      sleep 1
+    done
+    if [ "$dashboard_ready" != "1" ]; then
+      claude_smart_write_dashboard_unavailable "dashboard process spawned but did not respond on http://127.0.0.1:$PORT within 5s; see $LOG_FILE"
+    fi
+    emit_ok
+    ;;
+  stop)
+    if [ -f "$PID_FILE" ]; then
+      kill_group "$(cat "$PID_FILE" 2>/dev/null)"
+      rm -f "$PID_FILE"
+    fi
+    # Fallback: if our dashboard is still responding on the port (e.g.,
+    # was started outside this script, or the PGID kill missed because
+    # the process wasn't the group leader) kill whoever owns the port.
+    # Gated on the marker header so we never touch a foreign listener.
+    if marker_responds && command -v lsof >/dev/null 2>&1; then
+      port_pid=$(lsof -t -i ":$PORT" -sTCP:LISTEN 2>/dev/null | head -n1)
+      if [ -n "$port_pid" ]; then
+        kill -TERM "$port_pid" 2>/dev/null || true
+        for _ in 1 2 3 4 5; do
+          kill -0 "$port_pid" 2>/dev/null || break
+          sleep 0.2
+        done
+        kill -KILL "$port_pid" 2>/dev/null || true
+      fi
+    fi
+    emit_ok
+    ;;
+  session-end)
+    # Default: leave the dashboard running so users can keep browsing
+    # interactions/playbooks between sessions. Opt in to teardown by setting
+    # CLAUDE_SMART_DASHBOARD_STOP_ON_END=1 in the environment.
+    if [ "${CLAUDE_SMART_DASHBOARD_STOP_ON_END:-0}" = "1" ]; then
+      if [ -f "$PID_FILE" ]; then
+        kill_group "$(cat "$PID_FILE" 2>/dev/null)"
+        rm -f "$PID_FILE"
+      fi
+    fi
+    emit_ok
+    ;;
+  status)
+    if is_our_dashboard_running; then echo "running on http://localhost:$PORT"; else echo "not running"; fi
+    ;;
+  *)
+    emit_ok
+    ;;
+esac