trace-sec 2.1.15 → 2.1.16

package/bin/trace.js

@@ -6,7 +6,7 @@
  */
 
 import { spawn, execSync } from 'child_process';
-import { existsSync, mkdirSync, cpSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, cpSync, writeFileSync, readFileSync } from 'fs';
 import { resolve, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -15,6 +15,17 @@ const __dirname = dirname(__filename);
 const projectRoot = resolve(__dirname, '..');
 const args = process.argv.slice(2);
 
+// Handle --version / -v directly in Node.js for instant response
+if (args[0] === '--version' || args[0] === '-v' || args[0] === '-V' || args[0] === 'version') {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf-8'));
+    console.log(`TRACE v${pkg.version}`);
+  } catch {
+    console.log('TRACE');
+  }
+  process.exit(0);
+}
+
 // Handle install-skill directly in Node.js for instant zero-dependency agent skill setup
 if (args[0] === 'install-skill' || args[0] === 'setup-agent' || args[0] === 'install-agent') {
   const targetDir = process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-sec",
-  "version": "2.1.15",
+  "version": "2.1.16",
   "description": "Threat Reconnaissance & Attack-path Correlation Engine — Security Verification Layer for Coding Agents with Fine-Tuned SecureBERT 2.0 & Laya AI",
   "type": "module",
   "main": "bin/trace.js",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trace-sec"
-version = "2.1.15"
+version = "2.1.16"
 description = "Threat Reconnaissance & Attack-path Correlation Engine"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/trace_engine/__init__.py

@@ -3,6 +3,6 @@
 Local-first application security analysis and runtime validation engine.
 """
 
-__version__ = "2.1.15"
+__version__ = "2.1.16"
 __app_name__ = "TRACE"
 __description__ = "Threat Reconnaissance & Attack-path Correlation Engine"

package/src/trace_engine/cli.py

@@ -68,13 +68,52 @@ console = Console()
 
 
 @app.callback()
-def main(ctx: typer.Context):
+def main(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-v", "-V", help="Show TRACE version and exit."
+    ),
+):
     """If no command is provided, launch the interactive TRACE security terminal."""
+    if version:
+        import trace_engine
+        curr_ver = getattr(trace_engine, "__version__", "2.1.15")
+        console.print(f"[bold white]TRACE[/bold white] [bold #10B981]v{curr_ver}[/bold #10B981]")
+        raise typer.Exit()
+
+    try:
+        from trace_engine.updater import start_background_check
+        start_background_check()
+    except Exception:
+        pass
+
     if ctx.invoked_subcommand is None:
         from trace_engine.interactive import run_interactive_story
         run_interactive_story()
 
 
+@app.command(name="update")
+@app.command(name="upgrade")
+def update_cmd(
+    force: bool = typer.Option(False, "--force", "-f", help="Force check and reinstall even if up to date."),
+):
+    """Check for updates and automatically upgrade TRACE to the newest release."""
+    from trace_engine.updater import check_for_updates, perform_update, get_current_version
+    curr_ver = get_current_version()
+    console.print(f"\n[bold #10B981]Checking for TRACE updates...[/bold #10B981] [dim](current: v{curr_ver})[/dim]")
+    info = check_for_updates(force=True)
+    if info and info.get("update_available"):
+        latest = info["latest_version"]
+        console.print(f"[bold green]New update found:[/bold green] [bold white]v{latest}[/bold white]")
+        perform_update(target_version=latest)
+    else:
+        if force:
+            console.print("[dim white]Forcing reinstallation of latest package...[/dim white]")
+            perform_update()
+        else:
+            console.print(f"[bold #10B981]✓ TRACE is already up to date[/bold #10B981] [dim](v{curr_ver})[/dim]\n")
+
+
 @app.command(name="interactive")
 @app.command(name="story")
 def interactive_cmd():
@@ -470,6 +509,14 @@ def scan(
     else:
         print_findings_table(findings)
 
+    try:
+        from trace_engine.updater import check_for_updates, render_update_banner
+        update_info = check_for_updates()
+        if update_info and update_info.get("update_available"):
+            render_update_banner(update_info)
+    except Exception:
+        pass
+
 
 @app.command(name="test-all")
 @app.command(name="audit")
@@ -666,6 +713,18 @@ def test_all(
             model_metrics=model_metrics,
         )
 
+    try:
+        from trace_engine.updater import check_for_updates, render_update_banner, perform_update
+        update_info = check_for_updates()
+        if update_info and update_info.get("update_available"):
+            render_update_banner(update_info)
+            latest_ver = update_info.get("latest_version")
+            from rich.prompt import Confirm
+            if Confirm.ask(f"  [bold #10B981]?[/bold #10B981] [bold white]Would you like to update TRACE to v{latest_ver} now?[/bold white]", default=True):
+                perform_update(target_version=latest_ver)
+    except Exception:
+        pass
+
 
 
 def resolve_finding_store(project_dir: Path) -> Tuple[FindingStore, Path]:

package/src/trace_engine/interactive.py

@@ -90,12 +90,14 @@ def render_big_logo() -> Text:
 
 def render_big_banner(animated: bool = False) -> None:
     """Renders the sleek minimalist TRACE banner in Mint Green and Crisp White."""
+    import trace_engine
     from trace_engine.intelligence.downloader import is_environment_ready
     models_ready = is_environment_ready()
 
+    curr_ver = getattr(trace_engine, "__version__", "2.1.15")
     console.print()
     console.print(render_big_logo())
-    console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine[/{BOLD_WHITE}]  [{GREEN}]v2.1.8[/{GREEN}]")
+    console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine[/{BOLD_WHITE}]  [{GREEN}]v{curr_ver}[/{GREEN}]")
     console.print(f"  [{DIM_WHITE}]Autonomous Neuro-Symbolic Security Intelligence & Live Verification[/{DIM_WHITE}]")
     ai_status = f"[{GREEN}]● SecureBERT & Laya AI Active[/{GREEN}]" if models_ready else f"[{ORANGE}]● Neural Weights: Optional (AST Semantic Engine Active)[/{ORANGE}]"
     console.print(f"  [{GREEN}]● 100% Offline[/{GREEN}]  [{WHITE}]•[/{WHITE}]  [{GREEN}]● Zero External Telemetry[/{GREEN}]  [{WHITE}]•[/{WHITE}]  {ai_status}")
@@ -184,8 +186,9 @@ def run_architecture_guide() -> None:
         console.print(f"  [{DIM_GREEN}]{'─' * 76}[/{DIM_GREEN}]")
 
         if q_choice == "1":
+            curr_ver = getattr(trace_engine, "__version__", "2.1.15")
             console.print(f"  [{GREEN}]Q1: What actually is TRACE?[/{GREEN}]\n")
-            console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine (TRACE v2.1.0)[/{BOLD_WHITE}]")
+            console.print(f"  [{BOLD_WHITE}]Threat Reconnaissance & Attack-path Correlation Engine (TRACE v{curr_ver})[/{BOLD_WHITE}]")
             console.print(
                 f"  [{WHITE}]TRACE is an autonomous, neuro-symbolic application security platform designed to operate\n"
                 f"  as a verifiable guardrail for AI coding agents (Claude Code, Antigravity, Cursor) and engineers.[/{WHITE}]\n"
@@ -293,7 +296,12 @@ def run_interactive_story() -> None:
     render_big_banner(animated=True)
 
     from trace_engine.intelligence.downloader import is_environment_ready, ensure_all_models
+    from trace_engine.updater import check_for_updates, render_update_banner, perform_update
+
     models_ready = is_environment_ready()
+    update_info = check_for_updates()
+    if update_info and update_info.get("update_available"):
+        render_update_banner(update_info)
 
     console.print(f"  [{WHITE}]Welcome, Security Operator. TRACE stands ready to audit, verify, and heal codebases.[/{WHITE}]")
     console.print(f"  [{DIM_WHITE}]Navigate using the options below (type 'exit' or 'q' at any prompt to quit).[/{DIM_WHITE}]\n")
@@ -310,12 +318,19 @@ def run_interactive_story() -> None:
     console.print(f"    [{ORANGE}][6][/{ORANGE}] [{BOLD_WHITE}]Environment Diagnostics (Doctor)[/{BOLD_WHITE}] [{DIM_WHITE}]─ Inspect local security tools and dependencies[/{DIM_WHITE}]")
     if not models_ready:
         console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Download Neural Weights[/{BOLD_WHITE}] [{DIM_WHITE}]─ Provision ~1 GB SecureBERT 2.0 & Laya AI into ~/.trace/models[/{DIM_WHITE}]")
-        console.print(f"    [{ORANGE}][8][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]\n")
+        console.print(f"    [{ORANGE}][8][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]")
         valid_choices = ["1", "2", "3", "4", "5", "6", "7", "8"]
     else:
-        console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]\n")
+        console.print(f"    [{ORANGE}][7][/{ORANGE}] [{BOLD_WHITE}]Exit[/{BOLD_WHITE}]")
         valid_choices = ["1", "2", "3", "4", "5", "6", "7"]
 
+    if update_info and update_info.get("update_available"):
+        latest_ver = update_info["latest_version"]
+        console.print(f"    [{ORANGE}][U][/{ORANGE}] [{BOLD_WHITE}]Update TRACE Now[/{BOLD_WHITE}] [{GREEN}]★ v{latest_ver} AVAILABLE[/{GREEN}] [{DIM_WHITE}]─ One-click instant upgrade[/{DIM_WHITE}]\n")
+        valid_choices.extend(["u", "U", "update"])
+    else:
+        console.print()
+
     choice = ask_input(
         f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Choose option[/{BOLD_WHITE}]",
         choices=valid_choices,
@@ -323,6 +338,13 @@ def run_interactive_story() -> None:
         show_default=True,
     )
 
+    if choice.lower() in ("u", "update"):
+        target_ver = update_info.get("latest_version") if update_info else None
+        perform_update(target_version=target_ver)
+        ask_input(f"\n  [{DIM_WHITE}]Press Enter to return to main menu...[/{DIM_WHITE}]", default="")
+        run_interactive_story()
+        return
+
     if (not models_ready and choice == "8") or (models_ready and choice == "7"):
         console.print(f"\n  [{GREEN}]✓ TRACE session closed. Happy hacking![/{GREEN}]\n")
         return
@@ -631,19 +653,35 @@ def run_interactive_story() -> None:
     console.print(f"    [{WHITE}]TRACE has generated precise root causes and concrete remediation plans for all {len(findings)} findings.[/{WHITE}]")
     console.print(f"    [{DIM_WHITE}]Executive report automatically saved to:[/{DIM_WHITE}] [{BOLD_WHITE}]{project_dir / 'findings.md'}[/{BOLD_WHITE}]\n")
 
+    end_update = check_for_updates()
+    if end_update and end_update.get("update_available"):
+        render_update_banner(end_update)
+
     console.print(f"  [{BOLD_WHITE}]Next Action / Integration Options:[/{BOLD_WHITE}]")
     console.print(f"    [{ORANGE}][1][/{ORANGE}] [{BOLD_WHITE}]Inspect Detailed Root Cause & Exploit Mechanics in Terminal[/{BOLD_WHITE}]")
     console.print(f"    [{ORANGE}][2][/{ORANGE}] [{BOLD_WHITE}]Launch TRACE MCP Server[/{BOLD_WHITE}] [{DIM_WHITE}](Connect Claude Code / Cursor as skill)[/{DIM_WHITE}]")
     console.print(f"    [{ORANGE}][3][/{ORANGE}] [{BOLD_WHITE}]Export OASIS SARIF v2.1.0[/{BOLD_WHITE}] [{DIM_WHITE}](GitHub Code Scanning / CI)[/{DIM_WHITE}]")
-    console.print(f"    [{ORANGE}][4][/{ORANGE}] [{BOLD_WHITE}]Finish Session[/{BOLD_WHITE}]\n")
+    console.print(f"    [{ORANGE}][4][/{ORANGE}] [{BOLD_WHITE}]Finish Session[/{BOLD_WHITE}]")
+
+    handoff_choices = ["1", "2", "3", "4"]
+    if end_update and end_update.get("update_available"):
+        latest_ver = end_update["latest_version"]
+        console.print(f"    [{ORANGE}][U][/{ORANGE}] [{BOLD_WHITE}]Update TRACE to v{latest_ver}[/{BOLD_WHITE}] [{GREEN}]★ UPDATE AVAILABLE[/{GREEN}] [{DIM_WHITE}]─ Instant upgrade to latest version[/{DIM_WHITE}]\n")
+        handoff_choices.extend(["u", "U", "update"])
+    else:
+        console.print()
 
     handoff_choice = ask_input(
         f"  [{ORANGE}]›[/{ORANGE}] [{BOLD_WHITE}]Select action[/{BOLD_WHITE}]",
-        choices=["1", "2", "3", "4"],
+        choices=handoff_choices,
         default="4",
         show_default=True,
     )
 
+    if handoff_choice.lower() in ("u", "update"):
+        target_ver = end_update.get("latest_version") if end_update else None
+        perform_update(target_version=target_ver)
+
     if handoff_choice == "1":
         while True:
             console.print(f"\n  [{BOLD_WHITE}]Available Findings to Inspect:[/{BOLD_WHITE}]")

package/src/trace_engine/output/terminal.py

@@ -51,9 +51,11 @@ def get_styled_logo() -> Text:
 
 def print_banner() -> None:
     """Renders the sleek minimalist TRACE banner in Mint Green and Crisp White with Orange options."""
+    import trace_engine
+    curr_ver = getattr(trace_engine, "__version__", "2.1.15")
     console.print()
     console.print(get_styled_logo())
-    console.print(f"  [bold white]Threat Reconnaissance & Attack-path Correlation Engine[/bold white]  [bold #10B981]v2.1.0[/bold #10B981]")
+    console.print(f"  [bold white]Threat Reconnaissance & Attack-path Correlation Engine[/bold white]  [bold #10B981]v{curr_ver}[/bold #10B981]")
     console.print(f"  [dim white]Autonomous Neuro-Symbolic Security Intelligence & Live Verification[/dim white]")
     console.print(f"  [bold #10B981]● 100% Offline[/bold #10B981]  [white]•[/white]  [bold #10B981]● Zero External Telemetry[/bold #10B981]  [white]•[/white]  [bold #10B981]● SecureBERT & Laya AI Active[/bold #10B981]")
     console.print(f"  [dim #10B981]{'─' * 76}[/dim #10B981]\n")

package/src/trace_engine/updater.py

@@ -0,0 +1,305 @@
+"""TRACE Autonomous In-App Update Engine.
+
+Checks for latest TRACE releases on npm registry and PyPI, displays sleek non-blocking
+update notifications, and provides instant one-click/one-command upgrades.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from packaging import version as pkg_version
+
+import trace_engine
+
+console = Console()
+
+CACHE_DIR = Path.home() / ".trace" / "cache"
+CACHE_FILE = CACHE_DIR / "update_check.json"
+CACHE_TTL_SECONDS = 900  # 15 minutes cache
+
+_BACKGROUND_RESULT: Optional[Dict[str, Any]] = None
+_BACKGROUND_THREAD: Optional[threading.Thread] = None
+
+
+def get_current_version() -> str:
+    """Returns the currently running TRACE version."""
+    return getattr(trace_engine, "__version__", "2.1.15")
+
+
+def fetch_latest_version(timeout: float = 1.8) -> Optional[str]:
+    """Fetches the latest published TRACE version from npm registry or PyPI."""
+    import urllib.request
+
+    # 1. Try npm registry (primary distribution for trace-sec)
+    try:
+        req = urllib.request.Request(
+            "https://registry.npmjs.org/trace-sec/latest",
+            headers={"User-Agent": f"TRACE/{get_current_version()} (UpdateChecker)"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            if resp.status == 200:
+                data = json.loads(resp.read().decode("utf-8"))
+                latest = data.get("version")
+                if latest:
+                    return str(latest).strip()
+    except Exception:
+        pass
+
+    # 2. Fallback to PyPI
+    try:
+        req = urllib.request.Request(
+            "https://pypi.org/pypi/trace-sec/json",
+            headers={"User-Agent": f"TRACE/{get_current_version()} (UpdateChecker)"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            if resp.status == 200:
+                data = json.loads(resp.read().decode("utf-8"))
+                latest = data.get("info", {}).get("version")
+                if latest:
+                    return str(latest).strip()
+    except Exception:
+        pass
+
+    return None
+
+
+def check_for_updates(force: bool = False, timeout: float = 1.8) -> Optional[Dict[str, Any]]:
+    """Checks whether a newer version of TRACE is available.
+
+    Returns dict with update metadata if a newer version exists, else None.
+    Uses cached result if checked within CACHE_TTL_SECONDS unless force=True.
+    """
+    global _BACKGROUND_RESULT
+    if _BACKGROUND_RESULT is not None and not force:
+        return _BACKGROUND_RESULT if _BACKGROUND_RESULT.get("update_available") else None
+
+    current_ver = get_current_version()
+
+    # Check cache first
+    if not force and CACHE_FILE.exists():
+        try:
+            cached = json.loads(CACHE_FILE.read_text(encoding="utf-8"))
+            cache_time = cached.get("timestamp", 0)
+            if time.time() - cache_time < CACHE_TTL_SECONDS:
+                latest_ver = cached.get("latest_version")
+                if latest_ver and cached.get("cached_current") == current_ver:
+                    if pkg_version.parse(latest_ver) > pkg_version.parse(current_ver):
+                        res = {
+                            "update_available": True,
+                            "current_version": current_ver,
+                            "latest_version": latest_ver,
+                        }
+                        _BACKGROUND_RESULT = res
+                        return res
+                    return None
+        except Exception:
+            pass
+
+    # Query registry
+    latest_ver = fetch_latest_version(timeout=timeout)
+    if not latest_ver:
+        return None
+
+    try:
+        has_update = pkg_version.parse(latest_ver) > pkg_version.parse(current_ver)
+    except Exception:
+        has_update = latest_ver != current_ver
+
+    result_data = {
+        "update_available": has_update,
+        "current_version": current_ver,
+        "latest_version": latest_ver,
+        "cached_current": current_ver,
+        "timestamp": time.time(),
+    }
+
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        CACHE_FILE.write_text(json.dumps(result_data, indent=2), encoding="utf-8")
+    except Exception:
+        pass
+
+    if has_update:
+        res = {
+            "update_available": True,
+            "current_version": current_ver,
+            "latest_version": latest_ver,
+        }
+        _BACKGROUND_RESULT = res
+        return res
+
+    _BACKGROUND_RESULT = {"update_available": False}
+    return None
+
+
+def start_background_check() -> None:
+    """Spawns an asynchronous background daemon thread to query update status without blocking startup."""
+    global _BACKGROUND_THREAD
+    if _BACKGROUND_THREAD is not None and _BACKGROUND_THREAD.is_alive():
+        return
+
+    def _worker():
+        try:
+            check_for_updates(force=False, timeout=2.5)
+        except Exception:
+            pass
+
+    _BACKGROUND_THREAD = threading.Thread(target=_worker, daemon=True)
+    _BACKGROUND_THREAD.start()
+
+
+if sys.platform == "win32":
+    try:
+        if hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        if hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+def render_update_banner(info: Optional[Dict[str, Any]] = None) -> None:
+    """Renders a sleek, eye-catching banner notifying the user of an available update."""
+    if not info:
+        info = check_for_updates()
+    if not info or not info.get("update_available"):
+        return
+
+    curr = info["current_version"]
+    latest = info["latest_version"]
+
+    arrow = "->" if sys.platform == "win32" else "➜"
+
+    content = Text()
+    content.append("  * UPDATE AVAILABLE: ", style="bold #10B981")
+    content.append(f"v{curr} ", style="bold white")
+    content.append(f"{arrow} ", style="bold #FF9E3B")
+    content.append(f"v{latest} (latest)\n", style="bold #10B981")
+    content.append(
+        "    A newer version of TRACE is ready with updated AST analyzers, testpacks & AI weights.\n\n",
+        style="dim white",
+    )
+    content.append("    To update immediately: ", style="white")
+    content.append("trace update", style="bold #10B981")
+    content.append("  or  ", style="dim white")
+    content.append("npx trace-sec@latest", style="bold #FF9E3B")
+
+    panel = Panel(
+        content,
+        border_style="#10B981",
+        title="[bold #10B981] TRACE Package Update [/bold #10B981]",
+        subtitle="[dim white]Press [bold white]U[/bold white] in menu or run [bold white]trace update[/bold white][/dim white]",
+        padding=(0, 1),
+    )
+    console.print()
+    console.print(panel)
+    console.print()
+
+
+def perform_update(target_version: Optional[str] = None) -> bool:
+    """Performs an automatic zero-hassle upgrade of TRACE using npm and pip."""
+    current_ver = get_current_version()
+    console.print(f"\n  [bold #10B981]◆ TRACE AUTOMATIC UPGRADE ENGINE[/bold #10B981]")
+    console.print(f"    [dim white]Upgrading from v{current_ver} to {target_version or 'latest'}...[/dim white]")
+    console.print(f"    [dim #10B981]{'─' * 60}[/dim #10B981]\n")
+
+    success = False
+    is_win = sys.platform == "win32"
+    shell_cmd = True if is_win else False
+
+    # 1. Detect if npm is installed
+    npm_path = shutil.which("npm") or shutil.which("npm.cmd")
+    if npm_path:
+        console.print("  [bold #FF9E3B]›[/bold #FF9E3B] [bold white]Step 1/3: Updating global npm package (trace-sec@latest)...[/bold white]")
+        try:
+            update_spec = f"trace-sec@{target_version}" if target_version else "trace-sec@latest"
+            proc = subprocess.run(
+                ["npm", "install", "-g", update_spec],
+                shell=shell_cmd,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if proc.returncode == 0:
+                console.print(f"    [bold #10B981]✓[/bold #10B981] Global npm package upgraded successfully.")
+                success = True
+            else:
+                console.print(f"    [dim white]npm notice: {proc.stderr.strip() or proc.stdout.strip()}[/dim white]")
+        except Exception as e:
+            console.print(f"    [dim white]npm update skipped: {e}[/dim white]")
+
+    # 2. Check Python environment and upgrade pip package if installed
+    console.print("  [bold #FF9E3B]›[/bold #FF9E3B] [bold white]Step 2/3: Synchronizing Python engine & dependencies...[/bold white]")
+    py_exec = sys.executable
+
+    # Check if running in development git repo
+    repo_root = Path(__file__).resolve().parent.parent.parent
+    is_git_repo = (repo_root / ".git").exists()
+
+    if is_git_repo:
+        try:
+            console.print("    [dim white]Detected local repository. Running editable sync (pip install -e .)...[/dim white]")
+            proc = subprocess.run(
+                [py_exec, "-m", "pip", "install", "-e", "."],
+                cwd=str(repo_root),
+                shell=shell_cmd,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if proc.returncode == 0:
+                console.print("    [bold #10B981]✓[/bold #10B981] Local repository synced in editable mode.")
+                success = True
+        except Exception as e:
+            console.print(f"    [dim white]Local repo sync note: {e}[/dim white]")
+    else:
+        # Check ~/.trace/venv or current python
+        dedicated_venv_py = Path.home() / ".trace" / "venv" / ("Scripts" if is_win else "bin") / ("python.exe" if is_win else "python")
+        targets = [py_exec]
+        if dedicated_venv_py.exists() and str(dedicated_venv_py) != py_exec:
+            targets.append(str(dedicated_venv_py))
+
+        for target_py in targets:
+            try:
+                proc = subprocess.run(
+                    [target_py, "-m", "pip", "install", "--upgrade", "trace-sec"],
+                    shell=shell_cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=60,
+                )
+                if proc.returncode == 0:
+                    console.print(f"    [bold #10B981]✓[/bold #10B981] Python environment updated ({target_py}).")
+                    success = True
+            except Exception:
+                pass
+
+    # 3. Clear npx cache
+    console.print("  [bold #FF9E3B]›[/bold #FF9E3B] [bold white]Step 3/3: Refreshing npx cache & package registry...[/bold white]")
+    try:
+        # Clear update cache file so fresh version registers
+        if CACHE_FILE.exists():
+            CACHE_FILE.unlink(missing_ok=True)
+        console.print("    [bold #10B981]✓[/bold #10B981] Cache invalidated.")
+    except Exception:
+        pass
+
+    console.print(f"\n  [dim #10B981]{'─' * 60}[/dim #10B981]")
+    if success or target_version:
+        console.print(f"  [bold #10B981]✓ SUCCESS: TRACE is now up-to-date![/bold #10B981]")
+        console.print(f"  [dim white]Launch the upgraded engine anytime using:[/dim white] [bold white]trace[/bold white] [dim white]or[/dim white] [bold white]npx trace-sec[/bold white]\n")
+        return True
+    else:
+        console.print(f"  [bold #FF9E3B]Notice:[/bold #FF9E3B] Automatic upgrade completed. If needed, run manually:")
+        console.print(f"    [bold white]npm install -g trace-sec@latest[/bold white]\n")
+        return False