claude-smart 0.2.28 → 0.2.30

package/plugin/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-smart"
-version = "0.2.28"
+version = "0.2.30"
 description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
 readme = "README.md"
 requires-python = ">=3.12"

package/plugin/scripts/_lib.sh

@@ -233,6 +233,44 @@ claude_smart_npm_available() {
   "$npm_bin" --version >/dev/null 2>&1
 }
 
+claude_smart_log_max_bytes() {
+  printf '%s\n' "10000000"
+}
+
+claude_smart_trim_log_file() {
+  local file max_bytes size tmp
+  file="$1"
+  max_bytes="${2:-$(claude_smart_log_max_bytes)}"
+  case "$max_bytes" in
+    ''|*[!0-9]*) return 0 ;;
+  esac
+  [ -f "$file" ] || return 0
+  size=$(wc -c < "$file" 2>/dev/null | tr -d '[:space:]') || return 0
+  case "$size" in
+    ''|*[!0-9]*) return 0 ;;
+  esac
+  [ "$size" -le "$max_bytes" ] && return 0
+
+  tmp="${file}.trim.$$"
+  if tail -c "$max_bytes" "$file" > "$tmp" 2>/dev/null; then
+    # Rewrite the existing path instead of replacing it, so a process with
+    # this file already open in append mode keeps writing to the capped file.
+    cat "$tmp" > "$file"
+  fi
+  rm -f "$tmp"
+}
+
+claude_smart_append_capped_log() {
+  local file max_bytes
+  file="$1"
+  max_bytes="${2:-$(claude_smart_log_max_bytes)}"
+  shift 2
+  mkdir -p "$(dirname "$file")"
+  claude_smart_trim_log_file "$file" "$max_bytes"
+  printf '%s\n' "$*" >> "$file"
+  claude_smart_trim_log_file "$file" "$max_bytes"
+}
+
 # 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).

package/plugin/scripts/backend-log-runner.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Run the backend command and stream its stdout/stderr into a capped log file.
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_lib.sh
+. "$HERE/_lib.sh"
+
+if [ "$#" -lt 4 ] || [ "$3" != "--" ]; then
+  exit 2
+fi
+
+LOG_FILE="$1"
+MAX_BYTES="$2"
+shift 3
+
+mkdir -p "$(dirname "$LOG_FILE")"
+claude_smart_trim_log_file "$LOG_FILE" "$MAX_BYTES"
+
+STATUS_FILE="${TMPDIR:-/tmp}/claude-smart-backend-log-runner.$$.status"
+rm -f "$STATUS_FILE"
+
+(
+  set +e
+  "$@" 2>&1
+  printf '%s\n' "$?" > "$STATUS_FILE"
+) | while IFS= read -r line || [ -n "$line" ]; do
+  claude_smart_append_capped_log "$LOG_FILE" "$MAX_BYTES" "$line"
+done
+
+status=$(cat "$STATUS_FILE" 2>/dev/null || printf '1')
+rm -f "$STATUS_FILE"
+exit "$status"

package/plugin/scripts/backend-service.sh

@@ -41,9 +41,11 @@ PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 
 if [ -z "${CLAUDE_SMART_CLI_PATH:-}" ]; then
   if [ "${CLAUDE_SMART_HOST:-claude-code}" = "codex" ]; then
-    # Prefer the compatibility executable for older provider entrypoints; the
-    # provider can also resolve `codex` directly when this override is absent.
-    export CLAUDE_SMART_CLI_PATH="$PLUGIN_ROOT/scripts/codex-claude-compat.py"
+    # Reflexio's provider still calls CLAUDE_SMART_CLI_PATH with Claude CLI
+    # flags. Use a small compatibility executable that translates that narrow
+    # contract to `codex exec`.
+    claude_smart_prepend_node_bins
+    export CLAUDE_SMART_CLI_PATH="$PLUGIN_ROOT/scripts/codex-claude-compat"
   elif _cs_cli_path=$(command -v claude 2>/dev/null) && [ -n "$_cs_cli_path" ]; then
     export CLAUDE_SMART_CLI_PATH="$_cs_cli_path"
   elif [ -x "$HOME/.local/bin/claude" ]; then
@@ -55,7 +57,9 @@ fi
 STATE_DIR="$HOME/.claude-smart"
 PID_FILE="$STATE_DIR/backend.pid"
 LOG_FILE="$STATE_DIR/backend.log"
+LOG_MAX_BYTES="$(claude_smart_log_max_bytes)"
 mkdir -p "$STATE_DIR"
+claude_smart_trim_log_file "$LOG_FILE" "$LOG_MAX_BYTES"
 
 emit_ok() { echo '{"continue":true,"suppressOutput":true}'; }
 
@@ -178,12 +182,20 @@ case "$CMD" in
     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"
+      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: port $PORT held by another process; skipping"
       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
+      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; running installer"
+        CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >>"$STATE_DIR/install.log" 2>&1 || true
+        claude_smart_source_login_path
+        claude_smart_prepend_astral_bins
+      fi
+      if ! command -v uv >/dev/null 2>&1; then
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH after installer; skipping"
+        emit_ok; exit 0
+      fi
     fi
     cd "$PLUGIN_ROOT"
 
@@ -198,12 +210,12 @@ case "$CMD" in
     # 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
+    # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
+    # capture so process output cannot grow backend.log past its cap.
+    claude_smart_spawn_detached bash "$HERE/backend-log-runner.sh" \
+      "$LOG_FILE" "$LOG_MAX_BYTES" -- \
+      uv run --project "$PLUGIN_ROOT" --quiet \
+      reflexio services start --only backend --no-reload
     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;

package/plugin/scripts/cli.sh

@@ -32,9 +32,33 @@ if [ -f "$FAILURE_MARKER" ]; then
 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
+  # Self-heal: the Setup/SessionStart hook may have been skipped (trust
+  # prompt declined, plugin enabled mid-session, etc.) leaving the install
+  # half-done. Run smart-install.sh inline so the user does not have to
+  # restart Claude Code just to recover.
+  # Guard against recursion: if smart-install.sh ever shells back through
+  # this wrapper (e.g. a future migration step) we must not loop forever.
+  if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" = "1" ]; then
+    echo "claude-smart: bootstrap recursion detected; aborting." >&2
+    exit 1
+  fi
+  if [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+    echo "claude-smart: 'uv' not found — bootstrapping dependencies (~1-3 min on first install)..." >&2
+    CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >&2
+    claude_smart_prepend_astral_bins
+    claude_smart_prepend_node_bins
+  fi
+  if ! command -v uv >/dev/null 2>&1; then
+    if [ -f "$FAILURE_MARKER" ]; then
+      msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "unknown error")"
+      echo "claude-smart: install failed: $msg" >&2
+      echo "Fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
+    else
+      echo "claude-smart: 'uv' not found on PATH after bootstrap attempt." >&2
+      echo "Install it from https://docs.astral.sh/uv/ or rerun $PLUGIN_ROOT/scripts/smart-install.sh manually." >&2
+    fi
+    exit 1
+  fi
 fi
 
 exec uv run --project "$PLUGIN_ROOT" --quiet python -m claude_smart.cli "$@"

package/plugin/scripts/codex-claude-compat

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+case "$0" in
+  */*) SCRIPT_DIR=${0%/*} ;;
+  *) SCRIPT_DIR=. ;;
+esac
+SCRIPT_DIR=$(CDPATH= cd -- "$SCRIPT_DIR" && pwd)
+exec node "$SCRIPT_DIR/codex-claude-compat.js" "$@"

package/plugin/scripts/codex-claude-compat.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+set "SCRIPT_DIR=%~dp0"
+node "%SCRIPT_DIR%codex-claude-compat.js" %*

package/plugin/scripts/codex-claude-compat.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+"use strict";
+
+/*
+ * Translate Reflexio's Claude CLI provider contract to `codex exec`.
+ *
+ * Reflexio shells out to CLAUDE_SMART_CLI_PATH as if it were Claude Code:
+ *
+ *   <path> -p --output-format stream-json --model <model> ...
+ *
+ * Under Codex, this small bridge preserves that executable contract while
+ * routing the actual generation through the authenticated Codex CLI.
+ */
+
+const { spawnSync } = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const TIMEOUT_MS = 120_000;
+
+function main(argv) {
+  try {
+    const { outputFormat, systemPrompt } = parseSupportedArgs(argv);
+    const content = runCodex({
+      prompt: fs.readFileSync(0, "utf8"),
+      systemPrompt,
+    });
+    const payload =
+      outputFormat === "stream-json"
+        ? { type: "result", subtype: "success", result: content }
+        : { result: content };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`codex-claude-compat: ${message}\n`);
+    return 1;
+  }
+}
+
+function parseSupportedArgs(argv) {
+  let outputFormat = "json";
+  let systemPrompt = "";
+  let idx = 0;
+  while (idx < argv.length) {
+    const arg = argv[idx];
+    if (arg === "-p") {
+      idx += 1;
+    } else if (arg === "--output-format") {
+      outputFormat = requireValue(argv, idx, arg);
+      idx += 2;
+    } else if (arg === "--model") {
+      requireValue(argv, idx, arg);
+      idx += 2;
+    } else if (arg === "--verbose" || arg === "--include-partial-messages") {
+      idx += 1;
+    } else if (arg === "--append-system-prompt") {
+      systemPrompt = requireValue(argv, idx, arg);
+      idx += 2;
+    } else {
+      throw new Error(`unsupported Claude CLI argument: ${arg}`);
+    }
+  }
+  if (outputFormat !== "json" && outputFormat !== "stream-json") {
+    throw new Error(`unsupported --output-format: ${outputFormat}`);
+  }
+  return { outputFormat, systemPrompt };
+}
+
+function requireValue(argv, idx, name) {
+  if (idx + 1 >= argv.length) {
+    throw new Error(`${name} requires a value`);
+  }
+  return argv[idx + 1];
+}
+
+function runCodex({ prompt, systemPrompt }) {
+  const codexPath = process.env.CLAUDE_SMART_CODEX_PATH || commandPath(codexNames());
+  if (!codexPath) {
+    throw new Error("codex CLI not found on PATH");
+  }
+
+  const outputPath = temporaryOutputPath();
+  const args = [
+    "exec",
+    "--sandbox",
+    "read-only",
+    "--skip-git-repo-check",
+    "--ephemeral",
+    "--ignore-rules",
+    "--output-last-message",
+    outputPath,
+    "-",
+  ];
+  const env = {
+    ...process.env,
+    CLAUDE_SMART_HOST: "codex",
+    CLAUDE_SMART_INTERNAL: "1",
+    CLAUDE_CODE_ENTRYPOINT: "optimizer",
+  };
+
+  try {
+    const proc = spawnSync(codexPath, args, {
+      input: codexPrompt({ prompt, systemPrompt }),
+      encoding: "utf8",
+      env,
+      timeout: TIMEOUT_MS,
+      windowsHide: true,
+      shell: process.platform === "win32" && /\.(?:cmd|bat)$/i.test(codexPath),
+    });
+    if (proc.error) {
+      if (proc.error.code === "ETIMEDOUT") {
+        throw new Error(`codex CLI timed out after ${TIMEOUT_MS / 1000}s`);
+      }
+      throw proc.error;
+    }
+    if (proc.status !== 0) {
+      const stderr = String(proc.stderr || "").trim().slice(0, 500);
+      throw new Error(`codex CLI exited ${proc.status}: ${stderr}`);
+    }
+    const content = fs.readFileSync(outputPath, "utf8").trim();
+    if (!content) {
+      throw new Error("codex CLI returned empty output");
+    }
+    return content;
+  } finally {
+    try {
+      fs.unlinkSync(outputPath);
+    } catch {
+      // Best effort cleanup only.
+    }
+  }
+}
+
+function codexNames() {
+  return process.platform === "win32" ? ["codex.cmd", "codex.exe", "codex"] : ["codex"];
+}
+
+function commandPath(names) {
+  const pathParts = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  for (const dir of pathParts) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function temporaryOutputPath() {
+  const suffix = crypto.randomBytes(8).toString("hex");
+  return path.join(os.tmpdir(), `claude-smart-codex-${process.pid}-${Date.now()}-${suffix}`);
+}
+
+function codexPrompt({ prompt, systemPrompt }) {
+  if (!systemPrompt) return prompt;
+  return `${systemPrompt}\n\n## Task\n${prompt}`;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/plugin/scripts/codex-hook.js

@@ -13,6 +13,7 @@ const REFLEXIO_DIR = path.join(HOME, ".reflexio");
 const DEFAULT_BACKEND_PORT = 8071;
 const FALLBACK_BACKEND_PORT = 8072;
 const DASHBOARD_PORT = 3001;
+const LOG_MAX_BYTES = 10000000;
 
 function emitOk() {
   process.stdout.write('{"continue":true,"suppressOutput":true}\n');
@@ -22,9 +23,31 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
 
+function trimLog(file) {
+  if (!Number.isFinite(LOG_MAX_BYTES) || LOG_MAX_BYTES < 1) return;
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return;
+  }
+  if (!stat.isFile() || stat.size <= LOG_MAX_BYTES) return;
+  const fd = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(LOG_MAX_BYTES);
+    fs.readSync(fd, buffer, 0, LOG_MAX_BYTES, stat.size - LOG_MAX_BYTES);
+    fs.writeFileSync(file, buffer);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 function appendLog(name, line) {
   ensureDir(STATE_DIR);
-  fs.appendFileSync(path.join(STATE_DIR, name), `${line}\n`);
+  const file = path.join(STATE_DIR, name);
+  trimLog(file);
+  fs.appendFileSync(file, `${line}\n`);
+  trimLog(file);
 }
 
 function pluginRoot() {
@@ -81,6 +104,10 @@ function npmPath() {
   return commandPath(process.platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"]);
 }
 
+function bashPath() {
+  return commandPath(process.platform === "win32" ? ["bash.exe", "bash"] : ["bash"]);
+}
+
 function stateFile(name) {
   return path.join(STATE_DIR, name);
 }
@@ -95,7 +122,10 @@ function writeBackendUrl(port) {
 }
 
 function codexCompatPath(root) {
-  return path.join(root, "scripts", "codex-claude-compat.py");
+  const filename = process.platform === "win32"
+    ? "codex-claude-compat.cmd"
+    : "codex-claude-compat";
+  return path.join(root, "scripts", filename);
 }
 
 function readBackendUrl() {
@@ -176,6 +206,49 @@ function detached(command, args, options = {}) {
   return child.pid;
 }
 
+function runInstaller(root, reason) {
+  if (process.env.CLAUDE_SMART_BOOTSTRAPPING === "1") return false;
+  const script = path.join(root, "scripts", "smart-install.sh");
+  if (!fs.existsSync(script)) return false;
+  const bash = bashPath();
+  if (!bash) return false;
+  appendLog("backend.log", `[claude-smart] ${reason}; running installer`);
+  const result = spawnSync(bash, [script], {
+    cwd: root,
+    env: {
+      ...process.env,
+      CLAUDE_SMART_BOOTSTRAPPING: "1",
+    },
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    windowsHide: true,
+  });
+  const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  if (output) {
+    ensureDir(STATE_DIR);
+    fs.appendFileSync(path.join(STATE_DIR, "install.log"), `${output}\n`);
+    trimLog(path.join(STATE_DIR, "install.log"));
+  }
+  prependRuntimePath();
+  return result.status === 0;
+}
+
+function startInstallerDetached(root, reason) {
+  if (process.env.CLAUDE_SMART_BOOTSTRAPPING === "1") return false;
+  const script = path.join(root, "scripts", "smart-install.sh");
+  const bash = bashPath();
+  if (!bash || !fs.existsSync(script)) return false;
+  appendLog("backend.log", `[claude-smart] ${reason}; starting installer in background`);
+  detached(bash, [script], {
+    cwd: root,
+    env: {
+      ...process.env,
+      CLAUDE_SMART_BOOTSTRAPPING: "1",
+    },
+  });
+  return true;
+}
+
 function readPid(file) {
   try {
     const value = fs.readFileSync(file, "utf8").trim();
@@ -216,6 +289,7 @@ function ensurePluginRoot(root) {
 }
 
 async function startBackend(root) {
+  trimLog(path.join(STATE_DIR, "backend.log"));
   if (process.env.CLAUDE_SMART_BACKEND_AUTOSTART === "0") {
     emitOk();
     return;
@@ -235,7 +309,11 @@ async function startBackend(root) {
   }
   const uv = uvPath();
   if (!uv) {
-    appendLog("backend.log", "[claude-smart] backend: uv not on PATH; skipping");
+    runInstaller(root, "backend: uv not on PATH");
+  }
+  const readyUv = uvPath();
+  if (!readyUv) {
+    appendLog("backend.log", "[claude-smart] backend: uv not on PATH after installer; skipping");
     emitOk();
     return;
   }
@@ -257,7 +335,7 @@ async function startBackend(root) {
     INTERACTION_CLEANUP_DELETE_COUNT: process.env.INTERACTION_CLEANUP_DELETE_COUNT || "200",
   };
   const pid = detached(
-    uv,
+    readyUv,
     [
       "run",
       "--project",
@@ -299,14 +377,18 @@ async function startDashboard(root) {
   }
   const npm = npmPath();
   if (!npm) {
-    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH; skipping");
+    runInstaller(root, "dashboard: npm not on PATH");
+  }
+  const readyNpm = npmPath();
+  if (!readyNpm) {
+    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH after installer; skipping");
     emitOk();
     return;
   }
   if (!fs.existsSync(path.join(dashboard, ".next"))) {
     const buildPidFile = path.join(STATE_DIR, "dashboard-build.pid");
     if (!pidAlive(readPid(buildPidFile))) {
-      const pid = detached(npm, ["run", "build"], { cwd: dashboard });
+      const pid = detached(readyNpm, ["run", "build"], { cwd: dashboard });
       writePid(buildPidFile, pid);
       appendLog("dashboard.log", "[claude-smart] dashboard: .next missing; started background build");
     }
@@ -319,18 +401,27 @@ async function startDashboard(root) {
     REFLEXIO_URL: readBackendUrl(),
     CLAUDE_SMART_DASHBOARD_WORKSPACE: process.cwd(),
   };
-  const pid = detached(npm, ["run", "start"], { cwd: dashboard, env });
+  const pid = detached(readyNpm, ["run", "start"], { cwd: dashboard, env });
   writePid(pidFile, pid);
   await waitForHealth(DASHBOARD_PORT, "/api/health", "x-claude-smart-dashboard", 5);
   emitOk();
 }
 
 function runHook(root, event) {
-  const uv = uvPath();
+  trimLog(path.join(STATE_DIR, "backend.log"));
+  let uv = uvPath();
   if (!uv) {
-    appendLog("backend.log", "[claude-smart] hook: uv not on PATH; skipping");
-    emitOk();
-    return 0;
+    if (event === "session-start") {
+      runInstaller(root, "hook: uv not on PATH");
+      uv = uvPath();
+    } else {
+      startInstallerDetached(root, "hook: uv not on PATH");
+    }
+    if (!uv) {
+      appendLog("backend.log", "[claude-smart] hook: uv not on PATH after installer; skipping");
+      emitOk();
+      return 0;
+    }
   }
   const input = fs.readFileSync(0);
   const result = spawnSync(

package/plugin/scripts/dashboard-service.sh

@@ -100,10 +100,19 @@ case "$CMD" in
     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
+      if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" != "1" ] && [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+        echo "[claude-smart] dashboard: npm is not on PATH; running installer" >>"$LOG_FILE"
+        CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >>"$STATE_DIR/install.log" 2>&1 || true
+        claude_smart_source_login_path
+        claude_smart_prepend_node_bins
+        NPM_BIN=$(claude_smart_resolve_npm || true)
+      fi
+      if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
+        reason="npm is not on PATH after installer; dashboard cannot start"
+        echo "[claude-smart] dashboard: $reason; skipping" >>"$LOG_FILE"
+        claude_smart_write_dashboard_unavailable "$reason"
+        emit_ok; exit 0
+      fi
     fi
 
     # `npm run start` requires a prior `next build`. Do NOT build in the

package/plugin/scripts/hook_entry.sh

@@ -37,6 +37,7 @@ claude_smart_prepend_astral_bins
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
+STATE_DIR="$HOME/.claude-smart"
 if [ -f "$FAILURE_MARKER" ]; then
   if [ "$EVENT" = "session-start" ] && command -v python3 >/dev/null 2>&1; then
     python3 - "$FAILURE_MARKER" <<'PY'
@@ -61,9 +62,34 @@ PY
 fi
 
 if ! command -v uv >/dev/null 2>&1; then
-  # uv missing post-install → don't crash the session, just no-op.
-  echo '{"continue":true,"suppressOutput":true}'
-  exit 0
+  # Self-heal from skipped Setup/SessionStart bootstrap. SessionStart can
+  # afford to wait because it has the install budget; prompt/tool hooks start
+  # the same installer detached so normal work is not blocked by first-run
+  # dependency setup.
+  if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" = "1" ]; then
+    echo '{"continue":true,"suppressOutput":true}'
+    exit 0
+  fi
+  if [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+    mkdir -p "$STATE_DIR"
+    if [ "$EVENT" = "session-start" ]; then
+      CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >&2
+      claude_smart_prepend_astral_bins
+      claude_smart_prepend_node_bins
+      if command -v uv >/dev/null 2>&1; then
+        bash "$HERE/backend-service.sh" start >/dev/null 2>&1 || true
+        bash "$HERE/dashboard-service.sh" start >/dev/null 2>&1 || true
+      fi
+    else
+      claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+        bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+        >>"$STATE_DIR/install.log" 2>&1 || true
+    fi
+  fi
+  if ! command -v uv >/dev/null 2>&1; then
+    echo '{"continue":true,"suppressOutput":true}'
+    exit 0
+  fi
 fi
 
 # Stdin is the hook payload JSON — stream it through to the Python CLI.