claude-smart 0.2.40 → 0.2.42

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "reflexioai",
+  "owner": {
+    "name": "Yi Lu"
+  },
+  "metadata": {
+    "description": "claude-smart — self-improving Claude Code plugin via reflexio"
+  },
+  "plugins": [
+    {
+      "name": "claude-smart",
+      "version": "0.2.42",
+      "source": "./plugin",
+      "description": "Learns user corrections and project playbooks via reflexio — uses Claude Code itself as the LLM backend (no external API key required)"
+    }
+  ]
+}

package/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
   </a>
   <a href="plugin/pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.2.40-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.42-green.svg" alt="Version">
   </a>
   <a href="plugin/pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.12-brightgreen.svg" alt="Python">

package/bin/claude-smart.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 /**
  * npx claude-smart install — thin wrapper around the native host plugin
- * CLIs. For Claude Code it registers the GitHub marketplace and installs the
- * plugin. For Codex it copies the bundled local marketplace, registers it,
- * and enables plugin hooks. Both paths seed ~/.reflexio/.env with the two
- * local-provider flags so reflexio can route generation through local tools
- * with no API key. Managed/read-only/global setup is handled by
- * `npx claude-smart setup`, which writes ~/.reflexio/.env before running this
- * installer.
+ * CLIs. Both Claude Code and Codex install from the bundled marketplace in
+ * this npm package: Claude Code registers the package root as a local
+ * marketplace, and Codex copies the bundled plugin into its own marketplace
+ * wrapper. Both paths seed ~/.reflexio/.env with the two local-provider flags
+ * so reflexio can route generation through local tools with no API key.
+ * Managed/read-only/global setup is handled by `npx claude-smart setup`,
+ * which writes ~/.reflexio/.env before running this installer.
  *
  * Keep this file dependency-free — it runs via `npx` with no install step.
  */
@@ -33,7 +33,6 @@ const https = require("https");
 const { arch, homedir, platform, release, tmpdir } = require("os");
 const { dirname, join } = require("path");
 
-const DEFAULT_MARKETPLACE_SOURCE = "ReflexioAI/claude-smart";
 const PLUGIN_SPEC = "claude-smart@reflexioai";
 const CODEX_MARKETPLACE_NAME = "reflexioai";
 const CODEX_MARKETPLACE_DISPLAY_NAME = "ReflexioAI";
@@ -358,7 +357,7 @@ function findClaudeCodePluginRoot() {
       }
     }
   } catch {
-    // Fall through to marketplace/package fallbacks.
+    // Fall through to marketplace fallback.
   }
   candidates.sort((a, b) => {
     const versionCompare = compareSemverLikePathNames(b, a);
@@ -369,9 +368,13 @@ function findClaudeCodePluginRoot() {
       return 0;
     }
   });
+  // PACKAGE_ROOT/plugin is intentionally NOT a fallback: under `npx` it
+  // points at /root/.npm/_npx/<hash>/.../plugin which npm may prune between
+  // invocations, breaking the editable claude_smart install (.pth dangles,
+  // venv survives) and confusing every later `uv sync`. Require `claude
+  // plugin install` to have populated the cache dir instead, and fail loud.
   const fallbacks = [
     join(homedir(), ".claude", "plugins", "marketplaces", CODEX_MARKETPLACE_NAME, "plugin"),
-    join(PACKAGE_ROOT, "plugin"),
   ];
   for (const candidate of [...candidates, ...fallbacks]) {
     if (
@@ -429,7 +432,19 @@ function forcePluginRoot(pluginRoot) {
 async function bootstrapClaudeCodeInstall() {
   const pluginRoot = findClaudeCodePluginRoot();
   if (!pluginRoot) {
-    throw new Error("could not locate installed Claude Code plugin root after install");
+    const cacheRoot = join(
+      homedir(),
+      ".claude",
+      "plugins",
+      "cache",
+      CODEX_MARKETPLACE_NAME,
+      "claude-smart",
+    );
+    throw new Error(
+      `claude plugin install did not populate ${cacheRoot}. ` +
+        "Open Claude Code, run /plugins, verify claude-smart is installed " +
+        "from the ReflexioAI marketplace, then rerun `npx claude-smart install`.",
+    );
   }
   forcePluginRoot(pluginRoot);
   const bash = resolveCommand(isWindows() ? ["bash.exe", "bash"] : ["bash"]);
@@ -508,14 +523,14 @@ function runChecked(command, args, options = {}) {
   });
 }
 
-function runPluginService(pluginRoot, scriptName, subcommand) {
+function runPluginService(pluginRoot, scriptName, subcommand, envOverrides = {}) {
   const script = join(pluginRoot, "scripts", scriptName);
   if (!existsSync(script)) return false;
   const bash = resolveCommand(isWindows() ? ["bash.exe", "bash"] : ["bash"]);
   if (!bash) return false;
   const result = spawnSync(bash, [script, subcommand], {
     cwd: pluginRoot,
-    env: runtimeEnv(),
+    env: { ...runtimeEnv(), ...envOverrides },
     stdio: "ignore",
     windowsHide: true,
     timeout: PLUGIN_SERVICE_TIMEOUT_MS,
@@ -542,6 +557,12 @@ function refreshDashboardService(pluginRoot) {
   return runPluginService(pluginRoot, "dashboard-service.sh", "start");
 }
 
+function startBackendService(pluginRoot, host) {
+  return runPluginService(pluginRoot, "backend-service.sh", "start", {
+    CLAUDE_SMART_HOST: host,
+  });
+}
+
 function stopClaudeSmartServices(pluginRoot) {
   runPluginService(pluginRoot, "dashboard-service.sh", "stop");
   runPluginService(pluginRoot, "backend-service.sh", "stop");
@@ -834,9 +855,7 @@ function patchCodexHooksForNode(pluginRoot, nodePath) {
   const runner = join(pluginRoot, "scripts", "codex-hook.js");
   const command = (...args) => [nodePath, runner, ...args].map(quoteCommandPart).join(" ");
   // Dispatch by command content rather than index — entries can be added or
-  // reordered (e.g. the SessionStart install hook at index 0) without
-  // breaking the patch. Entries that must run as bash (smart-install.sh)
-  // are left untouched.
+  // reordered without breaking the patch.
   const patchOne = (original) => {
     if (typeof original !== "string") return original;
     if (original.includes("smart-install.sh")) return original;
@@ -956,13 +975,12 @@ function printHelp() {
       "Usage:",
       "  npx claude-smart install                       Install the plugin into Claude Code",
       "  npx claude-smart install --host codex          Register the plugin marketplace for Codex",
-      "  npx claude-smart install --source <owner/repo> Override the marketplace source",
       "  npx claude-smart setup                         Configure managed/read-only/global setup",
       "  npx claude-smart uninstall --host codex        Remove the Codex marketplace registration",
       "  npx claude-smart --help                        Show this help",
       "",
       "Claude Code install:",
-      "  1. claude plugin marketplace add <source>",
+      "  1. claude plugin marketplace add <this package>",
       `  2. claude plugin install ${PLUGIN_SPEC}`,
       "  3. Reads ~/.reflexio/.env when managed/read-only setup was configured.",
       "",
@@ -976,7 +994,8 @@ function printHelp() {
       "  7. Restart Codex.",
       "",
       "Update:",
-      "  npx claude-smart update                        Update to the latest version",
+      "  npx claude-smart update                        Reinstall Claude Code support from this package",
+      "  npx claude-smart update --host codex           Reinstall Codex support from this package",
       "  npx claude-smart setup                         Configure managed/read-only/global setup",
       "",
       "Uninstall:",
@@ -986,17 +1005,6 @@ function printHelp() {
   );
 }
 
-function parseSource(args) {
-  const idx = args.indexOf("--source");
-  if (idx === -1) return DEFAULT_MARKETPLACE_SOURCE;
-  const value = args[idx + 1];
-  if (!value) {
-    process.stderr.write("error: --source requires a value (e.g. owner/repo)\n");
-    process.exit(1);
-  }
-  return value;
-}
-
 function parseHost(args) {
   const idx = args.indexOf("--host");
   if (idx === -1) return "claude-code";
@@ -1392,33 +1400,53 @@ function installCodexPluginCache(pluginRoot) {
   return cacheDir;
 }
 
-async function runUpdate(args) {
-  const setup = configureReflexioSetup();
-  if (!hasClaudeCli()) {
-    process.stderr.write(
-      "error: 'claude' CLI not found on PATH. " +
-        "Install Claude Code first: https://claude.com/claude-code\n",
-    );
-    process.exit(1);
+function findCodexPluginRoot() {
+  const candidates = [];
+  try {
+    for (const entry of readdirSync(CODEX_PLUGIN_CACHE_DIR, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = join(CODEX_PLUGIN_CACHE_DIR, entry.name);
+      if (
+        existsSync(join(candidate, "pyproject.toml")) &&
+        existsSync(join(candidate, "scripts", "smart-install.sh"))
+      ) {
+        candidates.push(candidate);
+      }
+    }
+  } catch {
+    // No Codex cache yet.
   }
-
-  const code = await runClaude(["plugin", "update", PLUGIN_SPEC], {
-    spinnerLabel: "Checking for claude-smart updates…",
+  candidates.sort((a, b) => {
+    const versionCompare = compareSemverLikePathNames(b, a);
+    if (versionCompare !== 0) return versionCompare;
+    try {
+      return statSync(b).mtimeMs - statSync(a).mtimeMs;
+    } catch {
+      return 0;
+    }
   });
-  if (code !== 0) {
-    process.stderr.write(`error: \`claude plugin update ${PLUGIN_SPEC}\` failed (exit ${code})\n`);
-    process.exit(code);
+  return candidates[0] || null;
+}
+
+async function runUpdate(args) {
+  if (parseHost(args) === "codex") {
+    await runUpdateCodex(args);
+    return;
   }
 
-  process.stdout.write("\nclaude-smart updated. Restart Claude Code to apply.\n");
   const pluginRoot = findClaudeCodePluginRoot();
   if (pluginRoot) {
-    restorePublishHooksFromSource(pluginRoot);
-    if (setup.readOnly) {
-      prunePublishHooksForReadOnly(pluginRoot);
-      process.stdout.write("Installed read-only hook manifest; publish interactions hooks are disabled.\n");
-    }
+    stopClaudeSmartServices(pluginRoot);
   }
+  process.stdout.write("Updating claude-smart by reinstalling from this package...\n");
+  await runInstall(args, { retryInstallAfterUninstall: true });
+}
+
+async function runUpdateCodex(args) {
+  const pluginRoot = findCodexPluginRoot() || join(PACKAGE_ROOT, "plugin");
+  stopClaudeSmartServices(pluginRoot);
+  process.stdout.write("Updating claude-smart Codex support by reinstalling from this package...\n");
+  await runInstallCodex(args);
 }
 
 async function runUninstall(args) {
@@ -1471,7 +1499,7 @@ async function runSetup(args) {
   if (code !== 0) process.exit(code);
 }
 
-async function runInstall(args) {
+async function runInstall(args, options = {}) {
   if (parseHost(args) === "codex") {
     await runInstallCodex(args);
     return;
@@ -1485,7 +1513,7 @@ async function runInstall(args) {
     process.exit(1);
   }
 
-  const source = parseSource(args);
+  const source = PACKAGE_ROOT;
   const setup = configureReflexioSetup();
   const readOnly = setup.readOnly;
 
@@ -1495,7 +1523,21 @@ async function runInstall(args) {
   ];
 
   for (const step of steps) {
-    const code = await runClaude(step.args, { spinnerLabel: step.label });
+    let code = await runClaude(step.args, { spinnerLabel: step.label });
+    if (
+      code !== 0 &&
+      options.retryInstallAfterUninstall &&
+      step.args[0] === "plugin" &&
+      step.args[1] === "install"
+    ) {
+      process.stderr.write(
+        `warning: \`claude ${step.args.join(" ")}\` failed (exit ${code}); retrying after uninstalling ${PLUGIN_SPEC}.\n`,
+      );
+      await runClaude(["plugin", "uninstall", PLUGIN_SPEC], {
+        spinnerLabel: "Removing existing claude-smart install…",
+      });
+      code = await runClaude(step.args, { spinnerLabel: step.label });
+    }
     if (code !== 0) {
       process.stderr.write(
         `error: \`claude ${step.args.join(" ")}\` failed (exit ${code})\n`,
@@ -1512,6 +1554,9 @@ async function runInstall(args) {
       process.stdout.write("Installed read-only hook manifest; publish interactions hooks are disabled.\n");
     }
     process.stdout.write(`Prepared claude-smart runtime at ${pluginRoot}.\n`);
+    if (startBackendService(pluginRoot, "claude-code")) {
+      process.stdout.write("Started claude-smart backend service.\n");
+    }
     if (refreshDashboardService(pluginRoot)) {
       process.stdout.write("Refreshed claude-smart dashboard service.\n");
     }
@@ -1592,6 +1637,9 @@ async function runInstallCodex(args) {
     if (readOnly) {
       process.stdout.write("Installed read-only hook manifest; publish interactions hooks are disabled.\n");
     }
+    if (startBackendService(cacheDir, "codex")) {
+      process.stdout.write("Started claude-smart backend service.\n");
+    }
     if (refreshDashboardService(cacheDir)) {
       process.stdout.write("Refreshed claude-smart dashboard service.\n");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Self-improving Claude Code plugin — learns from corrections via reflexio",
   "keywords": [
     "claude",
@@ -29,6 +29,7 @@
     "bin",
     "scripts/setup-claude-smart.sh",
     ".agents/plugins/marketplace.json",
+    ".claude-plugin/marketplace.json",
     "plugin",
     "!plugin/**/__pycache__",
     "!plugin/**/*.py[cod]",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Self-improving Claude Code plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Self-improving coding assistant plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/dashboard/next.config.ts

@@ -1,7 +1,15 @@
 import type { NextConfig } from "next";
+import path from "path";
 
+// Pin Turbopack's workspace root to this dashboard directory. When the
+// plugin is installed via npx (e.g. ~/.npm/_npx/<hash>/node_modules/...),
+// Next would otherwise detect the npx parent's package-lock.json as the
+// workspace root and panic in `next build` ("Failed to write app endpoint
+// /page"). Pinning the root avoids that misdetection.
 const nextConfig: NextConfig = {
-  /* config options here */
+  turbopack: {
+    root: path.resolve(__dirname),
+  },
 };
 
 export default nextConfig;

package/plugin/hooks/codex-hooks.json

@@ -5,11 +5,6 @@
       {
         "matcher": "startup|resume",
         "hooks": [
-          {
-            "type": "command",
-            "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/smart-install.sh\" || true",
-            "timeout": 300
-          },
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$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",

package/plugin/hooks/hooks.json

@@ -14,16 +14,6 @@
       }
     ],
     "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/smart-install.sh\"",
-            "timeout": 300
-          }
-        ]
-      },
       {
         "matcher": "startup|clear|compact|resume",
         "hooks": [

package/plugin/pyproject.toml

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

package/plugin/scripts/backend-service.sh

@@ -138,20 +138,27 @@ 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 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=""
+  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
+    for pattern in "$@"; do
+      if [[ "$cmdline" == $pattern ]]; then
+        ours="$ours $pid"
+        break
+      fi
+    done
   done
   [ -z "$ours" ] && return 0
   # shellcheck disable=SC2086
@@ -166,16 +173,33 @@ reap_port_listeners() {
   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.
+# 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.
+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}'
+}
+
+# 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_stop() {
   if [ -f "$PID_FILE" ]; then
     kill_group "$(cat "$PID_FILE" 2>/dev/null)"
     rm -f "$PID_FILE"
   fi
-  reap_port_listeners
+  reap_port_listeners "$PORT" '*reflexio*' '*uvicorn*'
+  if [ -n "${EMBEDDING_PORT:-}" ] && [ "$EMBEDDING_PORT" != "$PORT" ]; then
+    reap_port_listeners "$EMBEDDING_PORT" \
+      '*reflexio.server.llm.embedding_service:app*' \
+      '*reflexio*embedding_service*'
+  fi
 }
 
 case "$CMD" in
@@ -195,19 +219,25 @@ case "$CMD" in
     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.
-      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: port $PORT held by another process; skipping"
+      # 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
       emit_ok; exit 0
     fi
     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; 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
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH; starting installer in background"
+        claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+          bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+          >>"$STATE_DIR/install.log" 2>&1 || true
       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"
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH; installer recovery scheduled; skipping"
         emit_ok; exit 0
       fi
     fi

package/plugin/scripts/cli.sh

@@ -45,7 +45,7 @@ if ! command -v uv >/dev/null 2>&1; then
   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_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >/dev/null
     claude_smart_prepend_astral_bins
     claude_smart_prepend_node_bins
   fi
@@ -63,4 +63,31 @@ if ! command -v uv >/dev/null 2>&1; then
   fi
 fi
 
+# Slash commands run synchronously and surface stderr directly to the user,
+# so a bare `python -m claude_smart.cli` ModuleNotFoundError leaks to the
+# transcript when the install is mid-bootstrap (e.g. SessionStart's
+# background smart-install.sh hasn't finished yet). Mirror hook_entry.sh's
+# ensure_hook_package_importable check: run smart-install.sh inline once,
+# then re-check, then surface either the install-failed marker reason or a
+# clear "still bootstrapping" message instead of letting Python crash.
+if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.cli; then
+  if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" != "1" ] \
+     && [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+    echo "claude-smart: finishing install (~1-3 min on first install)..." >&2
+    CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >/dev/null || true
+  fi
+  if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.cli; then
+    if [ -f "$FAILURE_MARKER" ]; then
+      msg="$(head -n 1 "$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
+    else
+      echo "claude-smart: claude_smart package is not importable in $PLUGIN_ROOT/.venv." >&2
+      echo "Run $PLUGIN_ROOT/scripts/smart-install.sh manually to diagnose." >&2
+    fi
+    exit 1
+  fi
+fi
+
 exec uv run --project "$PLUGIN_ROOT" --no-sync --quiet python -m claude_smart.cli "$@"

package/plugin/scripts/codex-hook.js

@@ -302,33 +302,6 @@ 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");
@@ -410,11 +383,11 @@ async function startBackend(root) {
   }
   const uv = uvPath();
   if (!uv) {
-    runInstaller(root, "backend: uv not on PATH");
+    startInstallerDetached(root, "backend: uv not on PATH");
   }
   const readyUv = uvPath();
   if (!readyUv) {
-    appendLog("backend.log", "[claude-smart] backend: uv not on PATH after installer; skipping");
+    appendLog("backend.log", "[claude-smart] backend: uv not on PATH; installer recovery scheduled; skipping");
     emitOk();
     return;
   }
@@ -478,11 +451,11 @@ async function startDashboard(root) {
   }
   const npm = npmPath();
   if (!npm) {
-    runInstaller(root, "dashboard: npm not on PATH");
+    startInstallerDetached(root, "dashboard: npm not on PATH");
   }
   const readyNpm = npmPath();
   if (!readyNpm) {
-    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH after installer; skipping");
+    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH; installer recovery scheduled; skipping");
     emitOk();
     return;
   }
@@ -512,14 +485,10 @@ function runHook(root, event) {
   trimLog(path.join(STATE_DIR, "backend.log"));
   let uv = uvPath();
   if (!uv) {
-    if (event === "session-start") {
-      runInstaller(root, "hook: uv not on PATH");
-      uv = uvPath();
-    } else {
-      startInstallerDetached(root, "hook: uv not on PATH");
-    }
+    startInstallerDetached(root, "hook: uv not on PATH");
+    uv = uvPath();
     if (!uv) {
-      appendLog("backend.log", "[claude-smart] hook: uv not on PATH after installer; skipping");
+      appendLog("backend.log", "[claude-smart] hook: uv not on PATH; installer recovery scheduled; skipping");
       emitHookOk();
       return 0;
     }

package/plugin/scripts/dashboard-service.sh

@@ -190,14 +190,13 @@ case "$CMD" in
     NPM_BIN=$(claude_smart_resolve_npm || true)
     if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
       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)
+        echo "[claude-smart] dashboard: npm is not on PATH; starting installer in background" >>"$LOG_FILE"
+        claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+          bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+          >>"$STATE_DIR/install.log" 2>&1 || 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"
+        reason="npm is not on PATH; installer recovery scheduled; dashboard cannot start yet"
         echo "[claude-smart] dashboard: $reason; skipping" >>"$LOG_FILE"
         claude_smart_write_dashboard_unavailable "$reason"
         emit_ok; exit 0

package/plugin/scripts/ensure-plugin-root.sh

@@ -1,11 +1,9 @@
 #!/usr/bin/env bash
 # Maintain ~/.reflexio/plugin-root as a symlink to the active plugin
-# install dir so slash commands can reference one short path regardless
-# of whether the user is on the remote marketplace (reflexioai) or the
-# local-dev marketplace (reflexioai-local).
+# install dir so slash commands can reference one short path.
 #
 # Usage: ensure-plugin-root.sh <target-dir> [--force]
-#   --force  overwrite any existing link (used by setup-local-dev.sh)
+#   --force  overwrite any existing link
 #   default  self-heal only if the link is missing or points at an
 #            invalid target
 set -eu
@@ -34,8 +32,7 @@ fi
 
 # Opt-in: when CLAUDE_SMART_PLUGIN_ROOT_FOLLOW_SESSION=1 (set in the
 # environment or in ~/.reflexio/.env), always relink to $TARGET so the
-# symlink tracks the currently loaded plugin. Off by default to preserve
-# a pinned local-dev link across sessions that load the remote plugin.
+# symlink tracks the currently loaded plugin.
 FOLLOW="${CLAUDE_SMART_PLUGIN_ROOT_FOLLOW_SESSION:-}"
 if [ -z "$FOLLOW" ] && [ -f "$HOME/.reflexio/.env" ]; then
     FOLLOW="$(grep -E '^CLAUDE_SMART_PLUGIN_ROOT_FOLLOW_SESSION=' "$HOME/.reflexio/.env" \
@@ -52,11 +49,9 @@ fi
 
 # Cache-tracking: if the link currently resolves to a path under the
 # managed plugin cache (~/.claude/plugins/cache/ or ~/.codex/plugins/cache/),
-# always retarget it to
-# $TARGET. Plugin updates leave old version directories behind, so a
-# valid pyproject.toml at the stale target is not proof the link is
-# fresh. Links pointing outside the cache (e.g., a user's local-dev
-# checkout) are left alone here and handled by the self-heal below.
+# always retarget it to $TARGET. Plugin updates leave old version
+# directories behind, so a valid pyproject.toml at the stale target is
+# not proof the link is fresh.
 if [ -L "$LINK" ]; then
     # Literal target string, not realpath: we compare against what was written by ln -s.
     CURRENT="$(readlink "$LINK" 2>/dev/null || true)"
@@ -74,9 +69,7 @@ if [ -L "$LINK" ]; then
 fi
 
 # Self-heal path: only rewrite the link if it's missing or its target is
-# gone/invalid. This preserves a valid local-dev symlink set earlier by
-# setup-local-dev.sh, so SessionStart hooks on the local install don't
-# clobber the user's repo-pointing link.
+# gone/invalid.
 if [ -f "$LINK/pyproject.toml" ]; then
     exit 0
 fi

package/plugin/scripts/hook_entry.sh

@@ -85,29 +85,18 @@ PY
 fi
 
 if ! command -v uv >/dev/null 2>&1; then
-  # 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.
+  # Self-heal from skipped setup without blocking the first prompt. The
+  # installer and Setup hook own dependency bootstrap; hooks only schedule
+  # recovery and return so SessionStart stays lightweight.
   if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" = "1" ]; then
     claude_smart_emit_continue
     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
+    claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+      bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+      >>"$STATE_DIR/install.log" 2>&1 || true
   fi
   if ! command -v uv >/dev/null 2>&1; then
     claude_smart_emit_continue
@@ -128,17 +117,13 @@ ensure_hook_package_importable() {
   fi
 
   mkdir -p "$STATE_DIR"
-  if [ "$EVENT" = "session-start" ]; then
-    CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >&2
-  else
-    {
-      printf '%s\n' "[claude-smart] hook: claude_smart.hook is not importable; retrying install in background"
-      date 2>/dev/null || true
-    } >>"$STATE_DIR/install.log" 2>&1
-    claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
-      bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
-      >>"$STATE_DIR/install.log" 2>&1 || true
-  fi
+  {
+    printf '%s\n' "[claude-smart] hook: claude_smart.hook is not importable; retrying install in background"
+    date 2>/dev/null || true
+  } >>"$STATE_DIR/install.log" 2>&1
+  claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+    bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+    >>"$STATE_DIR/install.log" 2>&1 || true
 
   claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook
 }

package/plugin/scripts/smart-install.sh

@@ -118,6 +118,13 @@ install_complete() {
   return 0
 }
 
+start_backend_service() {
+  if [ -x "$HERE/backend-service.sh" ]; then
+    echo "[claude-smart] starting backend service in background" >&2
+    bash "$HERE/backend-service.sh" start >/dev/null 2>&1 || true
+  fi
+}
+
 install_vendored_reflexio() {
   local VENDORED_REFLEXIO PLUGIN_PYTHON
 
@@ -391,6 +398,7 @@ fi
 preflight_supported_runtime_platform
 
 if install_complete; then
+  start_backend_service
   claude_smart_emit_continue
   exit 0
 fi
@@ -438,6 +446,22 @@ if ! command -v uv >/dev/null 2>&1; then
 fi
 
 cd "$PLUGIN_ROOT"
+# Self-heal a corrupt .venv before uv sync. uv refuses to reuse a venv that
+# exists but has no python executable (e.g. partial cleanup of an npm/npx
+# tree, an interrupted earlier install, or the underlying interpreter being
+# uninstalled) — it errors with "not a valid Python environment" instead of
+# rebuilding. Pre-clearing lets uv recreate it cleanly.
+if [ -d "$PLUGIN_ROOT/.venv" ]; then
+  if claude_smart_is_windows; then
+    plugin_python_path="$PLUGIN_ROOT/.venv/Scripts/python.exe"
+  else
+    plugin_python_path="$PLUGIN_ROOT/.venv/bin/python"
+  fi
+  if [ ! -x "$plugin_python_path" ]; then
+    echo "[claude-smart] .venv at $PLUGIN_ROOT/.venv has no python executable; recreating" >&2
+    rm -rf "$PLUGIN_ROOT/.venv"
+  fi
+fi
 echo "[claude-smart] running uv sync..." >&2
 if ! uv sync --locked --python 3.12 --quiet >&2; then
   write_failure "uv sync failed in $PLUGIN_ROOT — run 'uv sync --locked --python 3.12' there to diagnose"
@@ -618,12 +642,13 @@ elif [ -d "$DASHBOARD_DIR" ]; then
 fi
 
 # Point ~/.reflexio/plugin-root at this install so slash commands can
-# reference one stable short path regardless of which marketplace
-# (reflexioai or reflexioai-local) loaded us.
+# reference one stable short path regardless of which install loaded us.
 if ! bash "$HERE/ensure-plugin-root.sh" "$PLUGIN_ROOT"; then
   echo "[claude-smart] WARNING: failed to set ~/.reflexio/plugin-root symlink — slash commands may not resolve" >&2
 fi
 
+start_backend_service
+
 write_success_marker
-echo "[claude-smart] install complete. Backend and dashboard auto-start on session start." >&2
+echo "[claude-smart] install complete. Backend started; dashboard auto-starts on session start." >&2
 claude_smart_emit_continue

package/plugin/src/claude_smart/cli.py

@@ -38,7 +38,6 @@ from claude_smart.reflexio_adapter import Adapter
 
 _REFLEXIO_ENV_PATH = env_config.REFLEXIO_ENV_PATH
 _MANAGED_REFLEXIO_URL = env_config.MANAGED_REFLEXIO_URL
-_DEFAULT_MARKETPLACE_SOURCE = "ReflexioAI/claude-smart"
 _PLUGIN_SPEC = "claude-smart@reflexioai"
 _CODEX_MARKETPLACE_NAME = "reflexioai"
 _CODEX_MARKETPLACE_DISPLAY_NAME = "ReflexioAI"
@@ -803,6 +802,23 @@ def _install_codex_plugin_cache(plugin_root: Path) -> tuple[bool, str]:
     return True, f"installed Codex plugin cache at {cache_dir}"
 
 
+def _find_codex_plugin_root() -> Path | None:
+    """Locate the latest installed Codex plugin cache root."""
+    candidates = (
+        [
+            child
+            for child in _CODEX_PLUGIN_CACHE_DIR.iterdir()
+            if child.is_dir()
+            and (child / "pyproject.toml").is_file()
+            and (child / "scripts" / "smart-install.sh").is_file()
+        ]
+        if _CODEX_PLUGIN_CACHE_DIR.is_dir()
+        else []
+    )
+    candidates.sort(key=_installed_plugin_sort_key, reverse=True)
+    return candidates[0] if candidates else None
+
+
 def _cleanup_codex_install_state() -> bool:
     """Remove Codex's local install artifacts while preserving shared learning data.
 
@@ -1055,13 +1071,13 @@ def cmd_install_codex(args: argparse.Namespace) -> int:
 def cmd_install(args: argparse.Namespace) -> int:
     """Install claude-smart into Claude Code via the native plugin CLI.
 
-    Runs ``claude plugin marketplace add`` followed by ``claude plugin install``,
-    then appends the local-provider flags to ``~/.reflexio/.env`` so reflexio
-    can route generation through the local Claude Code CLI.
+    Runs ``claude plugin marketplace add`` (pointed at the bundled marketplace
+    at ``_REPO_ROOT``) followed by ``claude plugin install``, then appends the
+    local-provider flags to ``~/.reflexio/.env`` so reflexio can route
+    generation through the local Claude Code CLI.
 
     Args:
-        args (argparse.Namespace): Parsed CLI args. Uses ``args.source`` as the
-            marketplace ref (``owner/repo`` on GitHub, or a local directory).
+        args (argparse.Namespace): Parsed CLI args.
 
     Returns:
         int: 0 on success, non-zero if the ``claude`` CLI is missing or fails.
@@ -1077,13 +1093,27 @@ def cmd_install(args: argparse.Namespace) -> int:
         return 1
     read_only = _configure_reflexio_setup()
 
+    refresh_existing = bool(getattr(args, "refresh_existing", False))
     for cmd in (
-        ["claude", "plugin", "marketplace", "add", args.source],
+        ["claude", "plugin", "marketplace", "add", str(_REPO_ROOT)],
         ["claude", "plugin", "install", _PLUGIN_SPEC],
     ):
         try:
             subprocess.run(cmd, check=True)
         except subprocess.CalledProcessError as exc:
+            if refresh_existing and cmd[1:3] == ["plugin", "install"]:
+                sys.stderr.write(
+                    f"warning: {' '.join(cmd)} failed (exit {exc.returncode}); "
+                    f"retrying after uninstalling {_PLUGIN_SPEC}\n"
+                )
+                subprocess.run(
+                    ["claude", "plugin", "uninstall", _PLUGIN_SPEC], check=False
+                )
+                try:
+                    subprocess.run(cmd, check=True)
+                    continue
+                except subprocess.CalledProcessError as retry_exc:
+                    exc = retry_exc
             sys.stderr.write(f"error: {' '.join(cmd)} failed (exit {exc.returncode})\n")
             return exc.returncode or 1
 
@@ -1112,41 +1142,44 @@ def cmd_install(args: argparse.Namespace) -> int:
 
 
 def cmd_update(args: argparse.Namespace) -> int:
-    """Update claude-smart to the latest version via the native plugin CLI.
+    """Update claude-smart by reinstalling from this package.
 
-    Runs ``claude plugin update claude-smart@reflexioai``.
+    The simplified install path registers the bundled package root as the
+    marketplace, so update is a stop + reinstall instead of
+    ``claude plugin update``.
 
     Args:
-        args (argparse.Namespace): Parsed CLI args (unused).
+        args (argparse.Namespace): Parsed CLI args.
 
     Returns:
-        int: 0 on success, non-zero if the ``claude`` CLI is missing or fails.
+        int: 0 on success, non-zero if the host CLI is missing or install fails.
     """
-    if not shutil.which("claude"):
-        sys.stderr.write(
-            "error: 'claude' CLI not found on PATH. "
-            "Install Claude Code first: https://claude.com/claude-code\n"
-        )
-        return 1
+    if getattr(args, "host", "claude-code") == "codex":
+        return cmd_update_codex(args)
 
-    read_only = _configure_reflexio_setup()
-    cmd = ["claude", "plugin", "update", _PLUGIN_SPEC]
-    try:
-        subprocess.run(cmd, check=True)
-    except subprocess.CalledProcessError as exc:
-        sys.stderr.write(f"error: {' '.join(cmd)} failed (exit {exc.returncode})\n")
-        return exc.returncode or 1
+    _run_service(_DASHBOARD_SCRIPT, "stop")
+    _run_service(_BACKEND_SCRIPT, "stop")
+    sys.stdout.write("Updating claude-smart by reinstalling from this package...\n")
+    install_args = argparse.Namespace(**vars(args), refresh_existing=True)
+    install_args.host = "claude-code"
+    return cmd_install(install_args)
 
-    sys.stdout.write("\nclaude-smart updated. Restart Claude Code to apply.\n")
-    plugin_root = _find_claude_code_plugin_root()
+
+def cmd_update_codex(_args: argparse.Namespace) -> int:
+    """Update Codex support by refreshing its marketplace/cache install."""
+    plugin_root = _find_codex_plugin_root()
     if plugin_root is not None:
-        _restore_publish_hooks_from_source(plugin_root)
-        if read_only:
-            _prune_publish_hooks_for_read_only(plugin_root)
-            sys.stdout.write(
-                "Installed read-only hook manifest; publish interactions hooks are disabled.\n"
-            )
-    return 0
+        _run_service(plugin_root / "scripts" / "dashboard-service.sh", "stop")
+        _run_service(plugin_root / "scripts" / "backend-service.sh", "stop")
+    else:
+        _run_service(_DASHBOARD_SCRIPT, "stop")
+        _run_service(_BACKEND_SCRIPT, "stop")
+    sys.stdout.write(
+        "Updating claude-smart Codex support by reinstalling from this package...\n"
+    )
+    install_args = argparse.Namespace(**vars(_args))
+    install_args.host = "codex"
+    return cmd_install_codex(install_args)
 
 
 def cmd_uninstall(_args: argparse.Namespace) -> int:
@@ -1952,14 +1985,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default="claude-code",
         help="Install target host",
     )
-    inst.add_argument(
-        "--source",
-        default=_DEFAULT_MARKETPLACE_SOURCE,
-        help="Marketplace ref — GitHub owner/repo, or a local directory path",
-    )
     inst.set_defaults(func=cmd_install)
 
     upd = sub.add_parser("update", help="Update claude-smart to the latest version")
+    upd.add_argument(
+        "--host",
+        choices=("claude-code", "codex"),
+        default="claude-code",
+        help="Update target host",
+    )
     upd.set_defaults(func=cmd_update)
 
     uni = sub.add_parser("uninstall", help="Remove claude-smart")

package/plugin/uv.lock

@@ -419,7 +419,7 @@ wheels = [
 
 [[package]]
 name = "claude-smart"
-version = "0.2.40"
+version = "0.2.42"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },