nexo-brain 5.0.2 → 5.0.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -11,12 +11,12 @@
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 
 <p align="center">
-  <a href="https://www.youtube.com/watch?v=IBs7zh7ZMG0">
+  <a href="https://nexo-brain.com/watch/">
     <img src="assets/nexo-brain-infographic-v5.png" alt="NEXO Brain Architecture" width="700">
   </a>
 </p>
 
-[Watch the overview on YouTube](https://www.youtube.com/watch?v=IBs7zh7ZMG0) · [Watch the full deep-dive](https://www.youtube.com/watch?v=bKAfowyyy5M)
+[Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
@@ -87,6 +87,19 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
+Version `5.0.4` tightens the local runtime bridge and trims false-positive doctor noise:
+
+- vendorable `nexo_helper.py` now resolves `NEXO_HOME` and the `nexo` CLI path robustly, so personal scripts and subprocess flows stop depending on a lucky PATH
+- doctor no longer degrades because of advisory-only self-audit warnings or a single missing usage-telemetry row
+- managed Claude Code and Codex bootstraps now force an immediate first answer after simple email/diary/reminder/followup reads instead of feeling hung while chaining extra lookups
+
+Version `5.0.3` closes the next post-5.0 runtime gap:
+
+- `nexo chat` now boots Claude Code and Codex with an explicit NEXO startup prompt instead of opening cold or leaking the target path as a fake prompt
+- terminal launches now use the requested working directory as real `cwd`, so the selected project path stops behaving like chat text
+- the vendorable `nexo_helper.py` bridge now bounds helper calls with a timeout instead of letting personal-script subprocess flows wait forever
+- the doctor hardening from `5.0.2` remains validated on a real upgraded runtime after sync
+
 Version `5.0.2` closes the small post-5.0.1 doctor drift:
 
 - deep doctor now reads the live `learnings` schema correctly whether the install uses `status` or the older `archived` flag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/agent_runner.py

@@ -22,6 +22,7 @@ from client_preferences import (
     CLIENT_CODEX,
     TERMINAL_CLIENT_KEYS,
     load_client_preferences,
+    normalize_client_key,
     resolve_automation_backend,
     resolve_automation_task_profile,
     resolve_client_runtime_profile,
@@ -37,6 +38,11 @@ MODEL_PRICING_USD_PER_1M = {
     "gpt-5.4": {"input": 1.25, "cached_input": 0.125, "output": 10.0},
     "gpt-5.4-mini": {"input": 0.25, "cached_input": 0.025, "output": 2.0},
 }
+INTERACTIVE_STARTUP_PROMPT = (
+    "Start as NEXO for this session now. Use the managed bootstrap already installed "
+    "for this client, run nexo_startup and nexo_heartbeat for this first turn, then "
+    "reply with one concise startup status in the user's language."
+)
 
 
 class AgentRunnerError(RuntimeError):
@@ -312,6 +318,26 @@ def _codex_interactive_launch_flags() -> list[str]:
     return ["--sandbox", "danger-full-access", "--ask-for-approval", "never"]
 
 
+def _interactive_startup_prompt(client: str) -> str:
+    client_key = normalize_client_key(client)
+    if client_key in {CLIENT_CLAUDE_CODE, CLIENT_CODEX}:
+        return INTERACTIVE_STARTUP_PROMPT
+    return ""
+
+
+def _interactive_target_cwd(target: str | os.PathLike[str]) -> str:
+    candidate = Path(target).expanduser()
+    if candidate.exists() and candidate.is_file():
+        candidate = candidate.parent
+    try:
+        resolved = candidate.resolve()
+    except Exception:
+        resolved = candidate
+    if resolved.exists():
+        return str(resolved)
+    return str(Path.cwd())
+
+
 def build_interactive_client_command(
     *,
     target: str | os.PathLike[str],
@@ -322,6 +348,7 @@ def build_interactive_client_command(
     selected = resolve_terminal_client(client, preferences=prefs)
     target_path = str(Path(target).expanduser())
     profile = resolve_client_runtime_profile(selected, preferences=prefs)
+    startup_prompt = _interactive_startup_prompt(selected)
 
     if selected == CLIENT_CLAUDE_CODE:
         claude_bin = _resolve_claude_cli()
@@ -334,7 +361,9 @@ def build_interactive_client_command(
             cmd.extend(["--model", profile["model"]])
         if profile["reasoning_effort"]:
             cmd.extend(["--effort", profile["reasoning_effort"]])
-        cmd.extend(["--dangerously-skip-permissions", target_path])
+        cmd.append("--dangerously-skip-permissions")
+        if startup_prompt:
+            cmd.append(startup_prompt)
         return selected, cmd
 
     if selected == CLIENT_CODEX:
@@ -352,6 +381,8 @@ def build_interactive_client_command(
         if profile["reasoning_effort"]:
             cmd.extend(["-c", f'model_reasoning_effort="{profile["reasoning_effort"]}"'])
         cmd.extend(["-C", target_path])
+        if startup_prompt:
+            cmd.append(startup_prompt)
         return selected, cmd
 
     raise TerminalClientUnavailableError(f"Unsupported terminal client: {selected}")
@@ -368,7 +399,7 @@ def launch_interactive_client(
     launch_env = os.environ.copy()
     if env:
         launch_env.update(env)
-    return subprocess.run(cmd, env=launch_env)
+    return subprocess.run(cmd, env=launch_env, cwd=_interactive_target_cwd(target))
 
 
 def build_followup_terminal_shell_command(

package/src/cli.py

@@ -1081,6 +1081,8 @@ def _doctor(args):
         return 1
 
     init_db()
+    tier_label = getattr(args, "tier", "boot") or "boot"
+    print(f"[NEXO] Inspecting {tier_label} diagnostics... please wait.", file=sys.stderr, flush=True)
     report = run_doctor(tier=args.tier, fix=args.fix)
     output = format_report(report, fmt="json" if args.json else "text")
     print(output)

package/src/doctor/providers/deep.py

@@ -65,9 +65,6 @@ def check_self_audit_summary() -> DoctorCheck:
         if error_count > 0:
             status = "critical"
             severity = "error"
-        elif warn_count > 0:
-            status = "degraded"
-            severity = "warn"
         else:
             status = "healthy"
             severity = "info"

package/src/doctor/providers/runtime.py

@@ -41,6 +41,7 @@ PROTECTED_MACOS_ROOTS = (
 IMMUNE_FRESHNESS = 3600  # 1 hour (runs every 30 min)
 WATCHDOG_FRESHNESS = 3600  # 1 hour (runs every 30 min)
 DEFAULT_CRON_THRESHOLD = 7200  # Fallback when manifest data is unavailable
+LIVE_PROTOCOL_SESSION_FRESHNESS = 1800  # 30 minutes
 AUXILIARY_CORE_LAUNCHAGENT_IDS = {"dashboard", "prevent-sleep", "tcc-approve"}
 SPECIAL_LAUNCHAGENT_IDS = {"prevent-sleep", "tcc-approve"}
 SPECIAL_ENV_NORMALIZE_IDS = SPECIAL_LAUNCHAGENT_IDS
@@ -691,6 +692,37 @@ def _load_json(path: Path) -> dict:
     return json.loads(path.read_text())
 
 
+def _latest_cron_run_age_seconds(cron_id: str) -> float | None:
+    db_path = NEXO_HOME / "data" / "nexo.db"
+    if not db_path.is_file():
+        return None
+    try:
+        conn = sqlite3.connect(str(db_path), timeout=2)
+        try:
+            conn.row_factory = sqlite3.Row
+            table = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='cron_runs'"
+            ).fetchone()
+            if not table:
+                return None
+            row = conn.execute(
+                "SELECT MAX(started_at) AS last_run FROM cron_runs WHERE cron_id = ?",
+                (cron_id,),
+            ).fetchone()
+        finally:
+            conn.close()
+    except Exception:
+        return None
+
+    last_run = row["last_run"] if row else None
+    parsed = _parse_timestamp(last_run) if last_run else None
+    if parsed is None:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return max(0.0, time.time() - parsed.timestamp())
+
+
 def _latest_periodic_summary(kind: str) -> dict | None:
     pattern = f"*-{kind}-summary.json"
     candidates: list[tuple[str, Path]] = []
@@ -1097,22 +1129,9 @@ def check_immune_status() -> DoctorCheck:
         )
 
     age_min = age / 60
-    if age > IMMUNE_FRESHNESS:
-        return DoctorCheck(
-            id="runtime.immune_freshness",
-            tier="runtime",
-            status="degraded",
-            severity="warn",
-            summary=f"Immune status stale ({age_min:.0f} min old, threshold {IMMUNE_FRESHNESS // 60} min)",
-            evidence=[f"{status_file} last modified {age_min:.0f} minutes ago"],
-            repair_plan=[
-                "Check LaunchAgent/systemd timer for immune cron",
-                "nexo scripts call nexo_schedule_status --input '{}'",
-            ],
-            escalation_prompt="Investigate why immune system stopped refreshing.",
-        )
 
-    # Read status for additional context
+    # Read status for additional context even when the file is stale so the
+    # doctor can distinguish a dead immune cron from an intentional skip window.
     try:
         data = _load_json(status_file)
         counts = data.get("counts") or {}
@@ -1132,6 +1151,39 @@ def check_immune_status() -> DoctorCheck:
             status = "healthy"
             severity = "info"
             overall = "ok"
+        evidence: list[str] = []
+        if age > IMMUNE_FRESHNESS:
+            cron_age = _latest_cron_run_age_seconds("immune")
+            if cron_age is not None and cron_age <= IMMUNE_FRESHNESS:
+                evidence.append(
+                    f"immune cron ran {cron_age / 60:.0f} minutes ago; reusing last reported status while the cron remains alive"
+                )
+                summary = (
+                    f"Immune cron is alive; last status reused ({age_min:.0f} min old file)"
+                    if status == "healthy"
+                    else f"Immune cron is alive; last {overall} status reused ({age_min:.0f} min old file)"
+                )
+                return DoctorCheck(
+                    id="runtime.immune_freshness",
+                    tier="runtime",
+                    status=status,
+                    severity=severity,
+                    summary=summary,
+                    evidence=evidence,
+                )
+            return DoctorCheck(
+                id="runtime.immune_freshness",
+                tier="runtime",
+                status="degraded",
+                severity="warn",
+                summary=f"Immune status stale ({age_min:.0f} min old, threshold {IMMUNE_FRESHNESS // 60} min)",
+                evidence=[f"{status_file} last modified {age_min:.0f} minutes ago"],
+                repair_plan=[
+                    "Check LaunchAgent/systemd timer for immune cron",
+                    "nexo scripts call nexo_schedule_status --input '{}'",
+                ],
+                escalation_prompt="Investigate why immune system stopped refreshing.",
+            )
         return DoctorCheck(
             id="runtime.immune_freshness",
             tier="runtime",
@@ -2310,7 +2362,7 @@ def check_protocol_compliance() -> DoctorCheck:
                 tables = {
                     row["name"]
                     for row in conn.execute(
-                        "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('protocol_tasks', 'protocol_debt')"
+                        "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('protocol_tasks', 'protocol_debt', 'sessions')"
                     ).fetchall()
                 }
                 tasks = None
@@ -2323,14 +2375,78 @@ def check_protocol_compliance() -> DoctorCheck:
                            ORDER BY opened_at DESC""",
                         (window,),
                     ).fetchall()
-                    debt_rows = conn.execute(
-                        """SELECT severity, debt_type, COUNT(*) AS total
-                           FROM protocol_debt
-                           WHERE status = 'open' AND created_at >= datetime('now', ?)
-                           GROUP BY severity, debt_type
-                           ORDER BY total DESC, debt_type ASC""",
-                        (window,),
-                    ).fetchall()
+                    protocol_debt_cols = {
+                        row["name"] for row in conn.execute("PRAGMA table_info(protocol_debt)").fetchall()
+                    }
+                    protocol_task_cols = {
+                        row["name"] for row in conn.execute("PRAGMA table_info(protocol_tasks)").fetchall()
+                    }
+                    session_cols = set()
+                    if "sessions" in tables:
+                        session_cols = {
+                            row["name"] for row in conn.execute("PRAGMA table_info(sessions)").fetchall()
+                        }
+                    active_session_ids: set[str] = set()
+                    if {"sid", "last_update_epoch"}.issubset(session_cols):
+                        active_cutoff = time.time() - LIVE_PROTOCOL_SESSION_FRESHNESS
+                        active_session_ids = {
+                            str(row["sid"] or "")
+                            for row in conn.execute(
+                                "SELECT sid FROM sessions WHERE last_update_epoch >= ?",
+                                (active_cutoff,),
+                            ).fetchall()
+                        }
+                    live_guard_debt = 0
+                    if {"task_id", "session_id"}.issubset(protocol_debt_cols):
+                        task_status_expr = "'' AS task_status"
+                        if "status" in protocol_task_cols:
+                            task_status_expr = "pt.status AS task_status"
+                        open_debts = conn.execute(
+                            f"""SELECT
+                                    pd.severity,
+                                    pd.debt_type,
+                                    pd.session_id,
+                                    pd.task_id,
+                                    pd.created_at,
+                                    {task_status_expr}
+                                FROM protocol_debt pd
+                                LEFT JOIN protocol_tasks pt ON pt.task_id = pd.task_id
+                                WHERE pd.status = 'open' AND pd.created_at >= datetime('now', ?)
+                                ORDER BY pd.created_at DESC""",
+                            (window,),
+                        ).fetchall()
+                        debt_counter: dict[tuple[str, str], int] = {}
+                        for row in open_debts:
+                            severity = str(row["severity"] or "warn")
+                            debt_type = str(row["debt_type"] or "unknown")
+                            session_id = str(row["session_id"] or "")
+                            task_status = str(row["task_status"] or "")
+                            if (
+                                debt_type == "unacknowledged_guard_blocking"
+                                and task_status == "open"
+                                and session_id in active_session_ids
+                            ):
+                                live_guard_debt += 1
+                                continue
+                            debt_counter[(severity, debt_type)] = debt_counter.get((severity, debt_type), 0) + 1
+                        debt_rows = [
+                            {"severity": severity, "debt_type": debt_type, "total": total}
+                            for (severity, debt_type), total in sorted(
+                                debt_counter.items(),
+                                key=lambda item: (-item[1], item[0][1], item[0][0]),
+                            )
+                        ]
+                    else:
+                        debt_rows = [
+                            dict(row) for row in conn.execute(
+                                """SELECT severity, debt_type, COUNT(*) AS total
+                                   FROM protocol_debt
+                                   WHERE status = 'open' AND created_at >= datetime('now', ?)
+                                   GROUP BY severity, debt_type
+                                   ORDER BY total DESC, debt_type ASC""",
+                                (window,),
+                            ).fetchall()
+                        ]
                     has_cortex_evaluations = bool(
                         conn.execute(
                             "SELECT 1 FROM sqlite_master WHERE type='table' AND name='cortex_evaluations'"
@@ -2375,7 +2491,7 @@ def check_protocol_compliance() -> DoctorCheck:
                             if str(row["opened_at"] or "") >= first_cortex_eval_at
                         ]
                     decision_ok = [row for row in decision_eligible if row["task_id"] in covered_tasks]
-                    decision_metric_ready = len(decision_eligible) >= 3
+                    decision_metric_ready = bool(first_cortex_eval_at) and len(decision_eligible) >= 3
 
                     score_parts = []
                     if verify_required:
@@ -2417,6 +2533,8 @@ def check_protocol_compliance() -> DoctorCheck:
                             evidence.append("high-stakes decision-eval rollout not yet seeded in the live window")
                     for row in debt_rows[:5]:
                         evidence.append(f"open {row['severity']} debt — {row['debt_type']}: {row['total']}")
+                    if live_guard_debt:
+                        evidence.append(f"live in-progress guard acknowledgements pending: {live_guard_debt}")
 
                     repair_plan: list[str] = []
                     if verify_required and len(verify_ok) != len(verify_required):
@@ -2725,20 +2843,51 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
                     repair_plan=["Run NEXO migrations before trusting automation cost/parity metrics"],
                     escalation_prompt="Shared automation runs are happening without the telemetry table that release metrics depend on.",
                 )
-
-            row = conn.execute(
-                """
-                SELECT
-                    COUNT(*) AS runs,
-                    SUM(CASE WHEN (input_tokens + cached_input_tokens + output_tokens) > 0 THEN 1 ELSE 0 END) AS usage_runs,
-                    SUM(CASE WHEN total_cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS cost_runs,
-                    SUM(CASE WHEN cost_source = 'pricing_unavailable' THEN 1 ELSE 0 END) AS pricing_gaps,
-                    GROUP_CONCAT(DISTINCT backend) AS backends
-                FROM automation_runs
-                WHERE created_at >= datetime('now', ?)
-                """,
-                (f"-{days} days",),
-            ).fetchone()
+            columns = {
+                row["name"] for row in conn.execute("PRAGMA table_info(automation_runs)").fetchall()
+            }
+            schema_has_status = {
+                "status",
+                "input_tokens",
+                "cached_input_tokens",
+                "output_tokens",
+                "total_cost_usd",
+                "cost_source",
+                "backend",
+                "created_at",
+            }.issubset(columns)
+            if schema_has_status:
+                row = conn.execute(
+                    """
+                    SELECT
+                        COUNT(*) AS runs,
+                        SUM(CASE WHEN status = 'ok' THEN 1 ELSE 0 END) AS successful_runs,
+                        SUM(CASE WHEN status != 'ok' THEN 1 ELSE 0 END) AS failed_runs,
+                        SUM(CASE WHEN status = 'ok' AND (input_tokens + cached_input_tokens + output_tokens) > 0 THEN 1 ELSE 0 END) AS usage_runs,
+                        SUM(CASE WHEN status = 'ok' AND total_cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS cost_runs,
+                        SUM(CASE WHEN status = 'ok' AND cost_source = 'pricing_unavailable' THEN 1 ELSE 0 END) AS pricing_gaps,
+                        GROUP_CONCAT(DISTINCT backend) AS backends
+                    FROM automation_runs
+                    WHERE created_at >= datetime('now', ?)
+                    """,
+                    (f"-{days} days",),
+                ).fetchone()
+            else:
+                row = conn.execute(
+                    """
+                    SELECT
+                        COUNT(*) AS runs,
+                        COUNT(*) AS successful_runs,
+                        0 AS failed_runs,
+                        SUM(CASE WHEN (input_tokens + cached_input_tokens + output_tokens) > 0 THEN 1 ELSE 0 END) AS usage_runs,
+                        SUM(CASE WHEN total_cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS cost_runs,
+                        SUM(CASE WHEN cost_source = 'pricing_unavailable' THEN 1 ELSE 0 END) AS pricing_gaps,
+                        GROUP_CONCAT(DISTINCT backend) AS backends
+                    FROM automation_runs
+                    WHERE created_at >= datetime('now', ?)
+                    """,
+                    (f"-{days} days",),
+                ).fetchone()
         finally:
             conn.close()
     except Exception as exc:
@@ -2766,18 +2915,27 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
             escalation_prompt="",
         )
 
+    successful_runs = int((row["successful_runs"] if row else 0) or 0)
+    failed_runs = int((row["failed_runs"] if row else 0) or 0)
     usage_runs = int((row["usage_runs"] if row else 0) or 0)
     cost_runs = int((row["cost_runs"] if row else 0) or 0)
     pricing_gaps = int((row["pricing_gaps"] if row else 0) or 0)
-    usage_coverage = round((usage_runs / total_runs) * 100, 1)
-    cost_coverage = round((cost_runs / total_runs) * 100, 1)
+    usage_denominator = successful_runs or total_runs
+    cost_denominator = successful_runs or total_runs
+    missing_usage_runs = max(0, usage_denominator - usage_runs) if usage_denominator else 0
+    usage_coverage = round((usage_runs / usage_denominator) * 100, 1) if usage_denominator else 100.0
+    cost_coverage = round((cost_runs / cost_denominator) * 100, 1) if cost_denominator else 100.0
     evidence = [
         f"window={days}d",
         f"runs={total_runs}",
+        f"successful_runs={successful_runs}",
+        f"failed_runs={failed_runs}",
         f"usage_coverage={usage_coverage}%",
         f"cost_coverage={cost_coverage}%",
         f"pricing_gaps={pricing_gaps}",
     ]
+    if missing_usage_runs:
+        evidence.append(f"missing_usage_runs={missing_usage_runs}")
     backends = str((row["backends"] if row else "") or "").strip()
     if backends:
         evidence.append(f"backends={backends}")
@@ -2785,7 +2943,7 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
     status = "healthy"
     severity = "info"
     repair_plan: list[str] = []
-    if usage_coverage < 100.0:
+    if usage_coverage < 100.0 and missing_usage_runs > 1:
         status = "degraded"
         severity = "warn"
         repair_plan.append("Restore backend usage parsing so automation runs always emit token telemetry")

package/src/tools_drive.py

@@ -330,16 +330,17 @@ def _regex_fallback_classify(text: str) -> str | None:
     return None
 
 
-def _classify_signal(text: str) -> str | None:
+def _classify_signal(text: str, *, allow_llm: bool = True) -> str | None:
     """Classify text into a signal type, or None if nothing interesting."""
-    llm_result = _llm_classify_signal(text)
-    if llm_result.get("available"):
-        confidence = float(llm_result.get("confidence", 0.0) or 0.0)
-        label = llm_result.get("label")
-        if label is None and confidence >= _LLM_CONFIDENCE_THRESHOLD:
-            return None
-        if isinstance(label, str) and confidence >= _LLM_CONFIDENCE_THRESHOLD:
-            return label
+    if allow_llm:
+        llm_result = _llm_classify_signal(text)
+        if llm_result.get("available"):
+            confidence = float(llm_result.get("confidence", 0.0) or 0.0)
+            label = llm_result.get("label")
+            if label is None and confidence >= _LLM_CONFIDENCE_THRESHOLD:
+                return None
+            if isinstance(label, str) and confidence >= _LLM_CONFIDENCE_THRESHOLD:
+                return label
 
     scores = _semantic_signal_scores(text)
     if scores:
@@ -378,6 +379,8 @@ def detect_drive_signal(
     source: str,
     source_id: str = "",
     area: str = "",
+    *,
+    allow_llm: bool = False,
 ) -> dict | None:
     """Analyze text for interesting signals. Creates or reinforces.
 
@@ -387,7 +390,7 @@ def detect_drive_signal(
     if not context_hint or len(context_hint.strip()) < 15:
         return None
 
-    signal_type = _classify_signal(context_hint)
+    signal_type = _classify_signal(context_hint, allow_llm=allow_llm)
     if not signal_type:
         return None
 

package/src/tools_sessions.py

@@ -31,6 +31,14 @@ SESSION_PORTABILITY_DIR = NEXO_HOME / "operations" / "session-portability"
 _keepalive_threads: dict[str, threading.Event] = {}  # sid → stop_event
 
 
+def _env_flag(name: str, default: bool = False) -> bool:
+    """Parse a boolean environment flag with sane falsey values."""
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() not in {"", "0", "false", "no", "off"}
+
+
 def _keepalive_loop(sid: str, stop_event: threading.Event) -> None:
     """Periodically touch the session's last_update_epoch until stopped."""
     while not stop_event.wait(KEEPALIVE_INTERVAL):
@@ -522,7 +530,13 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
     try:
         if context_hint and len(context_hint.strip()) >= 15:
             from tools_drive import detect_drive_signal as _detect_drive
-            _drive_result = _detect_drive(context_hint, source="heartbeat", source_id=sid)
+            _drive_allow_llm = _env_flag("NEXO_DRIVE_LLM_IN_HEARTBEAT", default=False)
+            _drive_result = _detect_drive(
+                context_hint,
+                source="heartbeat",
+                source_id=sid,
+                allow_llm=_drive_allow_llm,
+            )
             if _drive_result:
                 # Check for READY signals relevant to current area
                 from db import get_drive_signals as _get_drive

package/templates/CLAUDE.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-claude-md-version: 2.1.2 -->
+<!-- nexo-claude-md-version: 2.1.3 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
@@ -28,6 +28,13 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 5. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
 6. On clear end-of-session intent, write the diary before replying.
 
+## Response Pacing
+- After the first relevant tool or artifact result, reply with the answer immediately instead of silently chaining more investigation.
+- Only continue into deeper investigation before the first visible answer if the user explicitly asked for a deep investigation or the situation is urgent/high-risk.
+- For single-artifact asks (email, message, diary item, reminder, prior fact), retrieve the artifact, summarize it, then decide whether further action is needed.
+- For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
+- After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first user-visible answer unless the user explicitly asked for it.
+
 <!-- nexo:start:profile -->
 ## User Profile
 - **Calibration:** `{{NEXO_HOME}}/brain/calibration.json` (personality settings + language + user name)

package/templates/CODEX.AGENTS.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-codex-agents-version: 1.2.2 -->
+<!-- nexo-codex-agents-version: 1.2.3 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — NEXO Shared Brain for Codex
@@ -25,6 +25,13 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 5. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
 6. On clear end-of-session intent, write the diary before replying.
 
+## Response Pacing
+- After the first relevant tool or artifact result, answer immediately instead of silently chaining more investigation.
+- Only keep investigating before the first visible answer if the user explicitly requested deep investigation or the situation is urgent/high-risk.
+- For single-artifact asks (email, message, diary item, reminder, prior fact), retrieve it, summarize it, then decide if more work is needed.
+- For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
+- After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first visible answer unless the user explicitly asked for it.
+
 ## Codex Runtime Notes
 - Codex does not provide Claude Code hooks, so protocol discipline must be explicit.
 - If a stable session token is useful, pass `session_token='codex-<task>-<date>'` and `session_client='codex'` to `nexo_startup`; otherwise leave them blank.

package/templates/nexo_helper.py

@@ -10,13 +10,36 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
 
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+def _detect_nexo_home() -> Path:
+    env_home = os.environ.get("NEXO_HOME", "").strip()
+    if env_home:
+        return Path(env_home).expanduser()
+
+    helper_path = Path(__file__).resolve()
+    inferred_home = helper_path.parent.parent
+    if (
+        helper_path.parent.name == "templates"
+        and (inferred_home / "scripts").is_dir()
+        and (inferred_home / "config").is_dir()
+    ):
+        return inferred_home
+
+    claude_home = Path.home() / "claude"
+    if claude_home.is_dir():
+        return claude_home
+
+    return Path.home() / ".nexo"
+
+
+NEXO_HOME = _detect_nexo_home()
 DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
+DEFAULT_NEXO_TIMEOUT_SECONDS = max(15, int(os.environ.get("NEXO_HELPER_TIMEOUT", "90")))
 
 
 def _load_schedule() -> dict:
@@ -48,15 +71,44 @@ def _load_bootstrap_prompt() -> str:
         return ""
 
 
+def _resolve_nexo_cli() -> str:
+    candidates = []
+
+    env_cli = os.environ.get("NEXO_BIN", "").strip()
+    if env_cli:
+        candidates.append(Path(env_cli).expanduser())
+
+    candidates.extend(
+        [
+            NEXO_HOME / "bin" / "nexo",
+            Path.home() / ".local" / "bin" / "nexo",
+            Path.home() / "bin" / "nexo",
+        ]
+    )
+
+    for candidate in candidates:
+        try:
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return str(candidate)
+        except OSError:
+            continue
+
+    return shutil.which("nexo") or "nexo"
+
+
 def run_nexo(args: list[str]) -> str:
     """Run a nexo CLI command and return stdout.
 
     Raises RuntimeError on non-zero exit.
     """
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
     result = subprocess.run(
-        ["nexo", *args],
+        [_resolve_nexo_cli(), *args],
         capture_output=True,
         text=True,
+        timeout=DEFAULT_NEXO_TIMEOUT_SECONDS,
+        env=env,
     )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"nexo exited {result.returncode}")
@@ -81,12 +133,72 @@ def call_tool_json(name: str, payload: dict | None = None) -> dict:
     return json.loads(out)
 
 
+def _extract_json_object(text: str) -> dict:
+    raw = str(text or "").strip()
+    if not raw:
+        raise RuntimeError("Automation backend returned empty output.")
+
+    if raw.startswith("```"):
+        lines = raw.splitlines()
+        if len(lines) >= 2:
+            end = len(lines)
+            for i in range(len(lines) - 1, 0, -1):
+                if lines[i].strip() == "```":
+                    end = i
+                    break
+            raw = "\n".join(lines[1:end]).strip()
+
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+
+    start = raw.find("{")
+    if start < 0:
+        raise RuntimeError("Automation backend did not return a JSON object.")
+
+    depth = 0
+    in_string = False
+    escape = False
+    for idx in range(start, len(raw)):
+        ch = raw[idx]
+        if in_string:
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            continue
+
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = raw[start : idx + 1]
+                try:
+                    parsed = json.loads(candidate)
+                except Exception as exc:
+                    raise RuntimeError(f"Automation backend returned invalid JSON object: {exc}") from exc
+                if isinstance(parsed, dict):
+                    return parsed
+                break
+
+    raise RuntimeError("Automation backend did not return a parseable JSON object.")
+
+
 def run_automation_text(
     prompt: str,
     *,
     model: str = "",
     reasoning_effort: str = "",
     cwd: str = "",
+    timeout: int | None = None,
     allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
     append_system_prompt: str = "",
     include_bootstrap: bool = True,
@@ -128,7 +240,58 @@ def run_automation_text(
         capture_output=True,
         text=True,
         env=env,
+        timeout=(int(timeout) if timeout else None),
     )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
     return result.stdout
+
+
+def run_automation_json(
+    prompt: str,
+    *,
+    model: str = "",
+    reasoning_effort: str = "",
+    cwd: str = "",
+    timeout: int | None = None,
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
+) -> dict:
+    """Run the configured backend and return a parsed JSON object."""
+    runner = NEXO_HOME / "scripts" / "nexo-agent-run.py"
+    if not runner.exists():
+        raise RuntimeError(f"Automation runner not found: {runner}")
+
+    cmd = [sys.executable, str(runner), "--prompt", prompt, "--output-format", "json"]
+    if model:
+        cmd.extend(["--model", model])
+    if reasoning_effort:
+        cmd.extend(["--reasoning-effort", reasoning_effort])
+    if cwd:
+        cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
+
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
+    env.setdefault("NEXO_CODE", env.get("NEXO_CODE", str(NEXO_HOME)))
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=(int(timeout) if timeout else None),
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
+    return _extract_json_object(result.stdout)