nexo-brain 7.17.6 → 7.17.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.17.6",
+  "version": "7.17.7",
   "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

@@ -18,7 +18,11 @@
 
 [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)
 
-Version `7.17.6` is the current packaged-runtime line. Patch release over v7.17.5 - cron health diagnostics are clearer for macOS TCC approval, and catch-up fallback executions now stay visible in `cron_runs` even on legacy or partially migrated runtimes.
+Version `7.17.7` is the current packaged-runtime line. Patch release over v7.17.6 - macOS TCC privacy denials now become a guided Full Disk Access permission state instead of an unexplained cron failure, with Desktop-ready status written for user action.
+
+Previously in `7.17.6`: patch release over v7.17.5 - cron health diagnostics are clearer for macOS TCC approval, and catch-up fallback executions now stay visible in `cron_runs` even on legacy or partially migrated runtimes.
+
+Previously in `7.17.5`: patch release over v7.17.4 - `nexo --version --json` now returns machine-readable update status so NEXO Desktop can populate the Updates panel without scraping slower human output.
 
 Previously in `7.17.4`: corrective patch over v7.17.3 - automation runners now keep full NEXO discipline for real background agents while strict JSON children stay clean, and runtime doctor/metrics expose caller coverage and Guardian injection telemetry instead of hiding blind spots.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.17.6",
+  "version": "7.17.7",
   "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/runtime_power.py

@@ -550,7 +550,12 @@ def _tail_has_permission_denial(log_file: Path) -> bool:
             size = fh.tell()
             fh.seek(max(size - 4096, 0))
             tail = fh.read().decode("utf-8", errors="ignore")
-        return "Operation not permitted" in tail
+        lowered = tail.lower()
+        return (
+            "operation not permitted" in lowered
+            or "authorization denied" in lowered
+            or "unable to open database" in lowered and "com.apple.tcc/tcc.db" in lowered
+        )
     except Exception:
         return False
 
@@ -568,10 +573,12 @@ def detect_full_disk_access_reasons(*, system: str | None = None) -> list[str]:
 
     logs_dir = paths.logs_dir()
     if logs_dir.is_dir():
-        for log_file in sorted(logs_dir.glob("*-stderr.log")):
+        log_files = list(logs_dir.glob("*-stderr.log"))
+        log_files.extend(logs_dir.glob("tcc-auto-approve.log"))
+        for log_file in sorted(log_files):
             if _tail_has_permission_denial(log_file):
                 reasons.append(
-                    f"Recent background job stderr hit 'Operation not permitted' ({log_file.name})"
+                    f"Recent background job hit a macOS privacy denial ({log_file.name})"
                 )
                 break
     return reasons

package/src/scripts/jargon_first_response.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""First-response jargon checker (Communication Guardrail enforcement).
+
+Implements followup NF-DS-32D6E12E: a linter that scans the FIRST visible
+message the agent emits in a turn for NEXO internal jargon that violates
+the Communication Guardrail in CLAUDE.md.
+
+Token list (case-insensitive substring match), taken verbatim from the
+followup spec:
+
+    Learning #, protocol debt, cortex eval, runtime-core, guard_check,
+    heartbeat, pre-emptive guard, enforcer, task_open, task_close, NF-
+
+Use as:
+
+* Library:
+    from src.scripts.jargon_first_response import scan_text, register_debt_if_violations
+
+* CLI (manual review of a recent reply):
+    echo "Learning #42 applied via task_open" \
+        | python3 src/scripts/jargon_first_response.py --stdin --session-id NEXO-SID
+
+* Future hook integration (PostToolUse / Stop) loads the transcript with
+  `transcript_utils.load_transcript` and pipes the latest assistant
+  message through `register_debt_if_violations`. Hook wiring is left as
+  a separate change so the linter ships independently testable.
+
+Exit codes (CLI):
+    0 — no violations detected (or only allowed because user requested detail)
+    1 — at least one prohibited token found
+    2 — invocation error (missing input)
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Iterable, List, Sequence
+
+# Order matters only for stable output. Longer / multi-word phrases first
+# so the snippet boundary is clearer in the matches view.
+PROHIBITED_TOKENS: Sequence[str] = (
+    "Learning #",
+    "protocol debt",
+    "cortex eval",
+    "runtime-core",
+    "guard_check",
+    "pre-emptive guard",
+    "enforcer",
+    "task_open",
+    "task_close",
+    "heartbeat",
+    "NF-",
+)
+
+# Heuristic signals from the *user* message that mean "operator asked for
+# technical detail, jargon is allowed in the reply". The first answer
+# only counts as a guardrail violation when none of these are present.
+_USER_DETAIL_PATTERNS = (
+    re.compile(r"\bdebugg(?:ing|er)?\b", re.IGNORECASE),
+    re.compile(r"\bstack\s*trace\b", re.IGNORECASE),
+    re.compile(r"\b(?:protocol\s+debt|guard_check|task_open|task_close|enforcer|heartbeat)\b", re.IGNORECASE),
+    re.compile(r"\b(?:nf-[a-z0-9-]+|learning\s+#?\d+)\b", re.IGNORECASE),
+    re.compile(r"\b(internal|runtime|architecture|cortex|drive)\b", re.IGNORECASE),
+    re.compile(r"\b(?:explica|explain|deep[\s-]*dive|d[ée]tailled|d[ée]tail)\b", re.IGNORECASE),
+)
+
+
+def _first_visible_paragraph(text: str) -> str:
+    """Return the first ~600 chars of operator-visible text.
+
+    Strips leading whitespace, blank lines, and ignores fenced code blocks
+    at the very top (release notes / code-only first messages are not
+    "first response prose" for the guardrail purpose).
+    """
+    if not text:
+        return ""
+    cleaned = text.lstrip()
+    if cleaned.startswith("```"):
+        end = cleaned.find("```", 3)
+        if end != -1:
+            cleaned = cleaned[end + 3 :].lstrip()
+    # First two paragraphs is usually plenty for the linter; longer
+    # replies have time to recover into plain language.
+    paragraphs = re.split(r"\n\s*\n", cleaned)
+    head = "\n\n".join(paragraphs[:2])
+    return head[:600]
+
+
+def user_requested_detail(user_message: str) -> bool:
+    """True if the operator explicitly asked for technical / NEXO-internal detail."""
+    if not user_message:
+        return False
+    return any(pat.search(user_message) for pat in _USER_DETAIL_PATTERNS)
+
+
+def scan_text(text: str, *, tokens: Iterable[str] = PROHIBITED_TOKENS) -> List[dict]:
+    """Return a list of `{token, index, snippet}` for each prohibited match."""
+    if not text:
+        return []
+    target = _first_visible_paragraph(text)
+    if not target:
+        return []
+    lowered = target.lower()
+    found: List[dict] = []
+    for token in tokens:
+        needle = token.lower()
+        start = 0
+        while True:
+            idx = lowered.find(needle, start)
+            if idx < 0:
+                break
+            snippet_start = max(0, idx - 25)
+            snippet_end = min(len(target), idx + len(token) + 25)
+            found.append({
+                "token": token,
+                "index": idx,
+                "snippet": target[snippet_start:snippet_end].replace("\n", " "),
+            })
+            start = idx + max(1, len(needle))
+    found.sort(key=lambda row: row["index"])
+    return found
+
+
+def register_debt_if_violations(
+    session_id: str,
+    assistant_text: str,
+    *,
+    user_message: str = "",
+    task_id: str = "",
+    evidence_prefix: str = "",
+) -> dict:
+    """Register a protocol_debt of type `communication_guardrail` when the
+    first response uses prohibited NEXO jargon and the user did NOT ask
+    for technical detail.
+
+    Returns a result dict with keys:
+        - `violations`: list of matches from `scan_text`
+        - `skipped`: bool — true if checker did not register (no SID, user
+            requested detail, or no violations)
+        - `debt_id`: int|None — id of the created debt, when applicable
+        - `reason`: short human-readable status
+    """
+    matches = scan_text(assistant_text)
+    if not matches:
+        return {"violations": [], "skipped": True, "debt_id": None, "reason": "no_violations"}
+    if user_requested_detail(user_message):
+        return {"violations": matches, "skipped": True, "debt_id": None, "reason": "user_requested_detail"}
+    sid = (session_id or "").strip()
+    if not sid:
+        return {"violations": matches, "skipped": True, "debt_id": None, "reason": "missing_session_id"}
+    try:
+        # Local import keeps this module importable in isolated test
+        # contexts (no NEXO DB) when callers only need `scan_text`.
+        sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+        from db import create_protocol_debt  # type: ignore
+    except Exception as err:  # pragma: no cover — defensive in tests
+        return {"violations": matches, "skipped": True, "debt_id": None, "reason": f"db_unavailable:{err}"}
+    evidence_lines = [evidence_prefix] if evidence_prefix else []
+    for match in matches[:5]:
+        evidence_lines.append(f"- '{match['token']}' @ {match['index']}: ...{match['snippet']}...")
+    evidence = "\n".join(line for line in evidence_lines if line)[:4000]
+    debt = create_protocol_debt(
+        sid,
+        "communication_guardrail",
+        severity="warn",
+        task_id=task_id,
+        evidence=evidence,
+    )
+    return {
+        "violations": matches,
+        "skipped": False,
+        "debt_id": debt.get("id") if isinstance(debt, dict) else None,
+        "reason": "debt_registered",
+    }
+
+
+def _read_text_from_args(args: argparse.Namespace) -> str:
+    if args.text is not None:
+        return args.text
+    if args.stdin:
+        return sys.stdin.read()
+    if args.file:
+        return Path(args.file).read_text(encoding="utf-8")
+    return ""
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="First-response jargon checker (NEXO Communication Guardrail).")
+    parser.add_argument("--text", help="Assistant text to scan (inline).")
+    parser.add_argument("--stdin", action="store_true", help="Read assistant text from stdin.")
+    parser.add_argument("--file", help="Read assistant text from file.")
+    parser.add_argument("--user-message", default="", help="Optional user message preceding the reply.")
+    parser.add_argument("--session-id", default=os.environ.get("NEXO_SID", ""), help="Session ID for protocol_debt registration.")
+    parser.add_argument("--task-id", default="", help="Optional task ID to attach to the debt.")
+    parser.add_argument("--register-debt", action="store_true", help="Register a protocol_debt when violations are found.")
+    parser.add_argument("--evidence-prefix", default="", help="Optional prefix for the evidence string.")
+    args = parser.parse_args(argv)
+
+    text = _read_text_from_args(args)
+    if not text:
+        parser.error("provide --text, --stdin, or --file")
+        return 2
+
+    if args.register_debt:
+        result = register_debt_if_violations(
+            args.session_id,
+            text,
+            user_message=args.user_message,
+            task_id=args.task_id,
+            evidence_prefix=args.evidence_prefix,
+        )
+        violations = result["violations"]
+    else:
+        violations = scan_text(text)
+        result = {
+            "violations": violations,
+            "skipped": True,
+            "debt_id": None,
+            "reason": "dry_run",
+        }
+
+    if not violations:
+        print("[jargon-checker] OK — no prohibited tokens in first response.")
+        return 0
+    print(f"[jargon-checker] {len(violations)} match(es) detected:")
+    for match in violations:
+        print(f"  - {match['token']!r} @ {match['index']}  …{match['snippet']}…")
+    if result.get("debt_id"):
+        print(f"[jargon-checker] protocol_debt registered id={result['debt_id']} reason=communication_guardrail")
+    elif args.register_debt:
+        print(f"[jargon-checker] no debt registered: {result.get('reason')}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/nexo-tcc-approve.sh

@@ -25,17 +25,99 @@ TCC_DB="$HOME/Library/Application Support/com.apple.TCC/TCC.db"
 VERSIONS_DIR="$HOME/.local/share/claude/versions"
 MARKER_DIR="$NEXO_HOME/runtime/data/.tcc-approved"
 LOG="$NEXO_HOME/runtime/logs/tcc-auto-approve.log"
+FDA_STATE="$NEXO_HOME/runtime/state/full-disk-access-required.json"
 
-mkdir -p "$MARKER_DIR" "$(dirname "$LOG")"
+mkdir -p "$MARKER_DIR" "$(dirname "$LOG")" "$(dirname "$FDA_STATE")"
 
 FAILED=0
+FDA_REQUIRED=0
 APPROVED_VERSIONS=0
 PYTHON_APPROVED=0
+FDA_REASON="macOS blocked tcc-approve from opening the user TCC database. Grant Full Disk Access to /bin/bash and NEXO Desktop, then retry background permission setup."
 
 log_line() {
     echo "$(date '+%Y-%m-%d %H:%M:%S') $*" >> "$LOG"
 }
 
+is_fda_error() {
+    local text
+    text="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
+    [[ "$text" == *"authorization denied"* ]] && return 0
+    [[ "$text" == *"operation not permitted"* ]] && return 0
+    [[ "$text" == *"unable to open database"* && "$text" == *"com.apple.tcc/tcc.db"* ]] && return 0
+    [[ "$text" == *"privacy"* && "$text" == *"com.apple.tcc"* ]] && return 0
+    return 1
+}
+
+python_for_state() {
+    local candidate
+    if [ -n "${NEXO_CODE:-}" ]; then
+        candidate="$(dirname "$NEXO_CODE")/.venv/bin/python"
+        [ -x "$candidate" ] && { echo "$candidate"; return 0; }
+        candidate="$(dirname "$NEXO_CODE")/.venv/bin/python3"
+        [ -x "$candidate" ] && { echo "$candidate"; return 0; }
+    fi
+    command -v python3 2>/dev/null || true
+}
+
+record_full_disk_access_required() {
+    local py
+    py="$(python_for_state)"
+
+    cat > "$FDA_STATE" <<EOF
+{
+  "status": "later",
+  "source": "tcc-approve",
+  "updated_at": "$(date -u '+%Y-%m-%dT%H:%M:%SZ')",
+  "reasons": [
+    "$FDA_REASON"
+  ]
+}
+EOF
+
+    [ -n "$py" ] || return 0
+    NEXO_FDA_REASON="$FDA_REASON" NEXO_HOME="$NEXO_HOME" "$py" <<'PY'
+import json
+import os
+from pathlib import Path
+
+nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+reason = os.environ.get("NEXO_FDA_REASON", "").strip()
+targets = [nexo_home / "personal" / "config" / "schedule.json"]
+legacy = nexo_home / "config" / "schedule.json"
+if legacy.exists():
+    targets.append(legacy)
+
+seen = set()
+for target in targets:
+    key = str(target.resolve(strict=False))
+    if key in seen:
+        continue
+    seen.add(key)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        data = {}
+        if target.exists():
+            try:
+                parsed = json.loads(target.read_text(encoding="utf-8"))
+                if isinstance(parsed, dict):
+                    data = parsed
+            except Exception:
+                data = {}
+        reasons = data.get("full_disk_access_reasons")
+        if not isinstance(reasons, list):
+            reasons = []
+        if reason and reason not in reasons:
+            reasons.append(reason)
+        data["full_disk_access_status"] = "later"
+        data["full_disk_access_status_version"] = 1
+        data["full_disk_access_reasons"] = reasons
+        target.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except Exception:
+        pass
+PY
+}
+
 approve_service() {
     local svc="$1"
     local client="$2"
@@ -49,6 +131,9 @@ approve_service() {
     fi
 
     log_line "WARN: failed TCC approval service=$svc client=$client: ${output:-sqlite3 failed}"
+    if is_fda_error "${output:-}"; then
+        FDA_REQUIRED=1
+    fi
     return 1
 }
 
@@ -119,6 +204,13 @@ if [ -n "$NEXO_CODE" ]; then
     fi
 fi
 
+if [ "$FAILED" -ne 0 ] && [ "$FDA_REQUIRED" -ne 0 ]; then
+    record_full_disk_access_required
+    log_line "Full Disk Access required: $FDA_REASON"
+    echo "TCC auto-approve: Full Disk Access required; Desktop will prompt the user"
+    exit 0
+fi
+
 if [ "$FAILED" -ne 0 ]; then
     echo "TCC auto-approve failed; see $LOG" >&2
     exit 1