nexo-brain 2.7.0 → 3.0.0

package/src/tools_learnings.py

@@ -1,11 +1,267 @@
 """Learnings CRUD tools: add, search, update, delete, list."""
 
+import re
+from datetime import datetime
+
 from db import (create_learning, update_learning, delete_learning, search_learnings,
-                list_learnings, find_similar_learnings, get_db, now_epoch)
+                list_learnings, find_similar_learnings, get_db, now_epoch, supersede_learning)
+
+NEGATION_PATTERNS = (
+    "do not", "don't", "never", "avoid", "skip", "without", "forbid", "forbidden",
+    "disable", "disabled", "remove", "ban", "bypass",
+)
+CONTRADICTION_PAIRS = (
+    ("enable", "disable"),
+    ("use", "avoid"),
+    ("add", "remove"),
+    ("allow", "forbid"),
+    ("always", "never"),
+    ("before", "after"),
+    ("require", "skip"),
+    ("validate", "skip"),
+    ("validate", "bypass"),
+    ("include", "exclude"),
+)
+
+
+def _split_applies_to(applies_to: str) -> list[str]:
+    return [item.strip() for item in str(applies_to or "").split(",") if item.strip()]
+
+
+def _normalize_applies_token(value: str) -> str:
+    return str(value or "").replace("\\", "/").rstrip("/").lower()
+
+
+def _applies_overlap(left: str, right: str) -> bool:
+    left_tokens = {_normalize_applies_token(item) for item in _split_applies_to(left)}
+    right_tokens = {_normalize_applies_token(item) for item in _split_applies_to(right)}
+    left_tokens.discard("")
+    right_tokens.discard("")
+    if not left_tokens or not right_tokens:
+        return False
+    if left_tokens & right_tokens:
+        return True
+    for left_token in left_tokens:
+        for right_token in right_tokens:
+            if "/" in left_token or "/" in right_token:
+                if left_token.startswith(f"{right_token}/") or right_token.startswith(f"{left_token}/"):
+                    return True
+                if left_token.endswith(f"/{right_token}") or right_token.endswith(f"/{left_token}"):
+                    return True
+    return False
+
+
+def _normalize_text(text: str) -> str:
+    return re.sub(r"\s+", " ", str(text or "").strip().lower())
+
+
+def _tokenize(text: str) -> list[str]:
+    return re.findall(r"[a-z0-9_-]+", _normalize_text(text))
+
+
+def _contains_negation(text: str) -> bool:
+    lowered = _normalize_text(text)
+    return any(token in lowered for token in NEGATION_PATTERNS)
+
+
+def _negated_action_verbs(text: str) -> set[str]:
+    lowered = _normalize_text(text)
+    matches = set()
+    for pattern in (
+        r"(?:never|avoid|skip|disable|remove|forbid|bypass)\s+([a-z0-9_-]+)",
+        r"(?:do not|don't)\s+([a-z0-9_-]+)",
+    ):
+        matches.update(re.findall(pattern, lowered))
+    return {match for match in matches if len(match) > 2}
+
+
+def _looks_contradictory(existing_text: str, new_text: str) -> bool:
+    existing_norm = _normalize_text(existing_text)
+    new_norm = _normalize_text(new_text)
+    if not existing_norm or not new_norm:
+        return False
+    existing_tokens = set(_tokenize(existing_norm))
+    new_tokens = set(_tokenize(new_norm))
+    if not (existing_tokens & new_tokens):
+        return False
+    existing_negated_verbs = _negated_action_verbs(existing_norm)
+    new_negated_verbs = _negated_action_verbs(new_norm)
+    if existing_negated_verbs & new_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if new_negated_verbs & existing_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if _contains_negation(existing_norm) != _contains_negation(new_norm):
+        return True
+    for positive, negative in CONTRADICTION_PAIRS:
+        existing_has_pair = positive in existing_norm or negative in existing_norm
+        new_has_pair = positive in new_norm or negative in new_norm
+        if existing_has_pair and new_has_pair:
+            if (positive in existing_norm and negative in new_norm) or (negative in existing_norm and positive in new_norm):
+                return True
+    return False
+
+
+def _find_conflicting_active_learning(conn, *, category: str, title: str, content: str,
+                                      applies_to: str, exclude_id: int | None = None) -> dict | None:
+    if not applies_to:
+        return None
+    params = [category]
+    sql = (
+        "SELECT id, title, content, applies_to FROM learnings "
+        "WHERE category = ? AND status = 'active' AND COALESCE(applies_to, '') != ''"
+    )
+    if exclude_id is not None:
+        sql += " AND id != ?"
+        params.append(exclude_id)
+    rows = conn.execute(sql, tuple(params)).fetchall()
+    incoming_text = f"{title} {content}"
+    for row in rows:
+        if not _applies_overlap(row["applies_to"], applies_to):
+            continue
+        if _looks_contradictory(f"{row['title']} {row['content']}", incoming_text):
+            return dict(row)
+    return None
+
+
+def find_conflicting_active_learning(*, category: str, title: str, content: str,
+                                     applies_to: str, exclude_id: int | None = None) -> dict | None:
+    """Public wrapper for canonical-rule enforcement on file-scoped learnings."""
+    conn = get_db()
+    return _find_conflicting_active_learning(
+        conn,
+        category=category.lower().strip(),
+        title=title,
+        content=content,
+        applies_to=applies_to,
+        exclude_id=exclude_id,
+    )
+
+
+def _priority_score(priority: str) -> float:
+    return {
+        "critical": 1.0,
+        "high": 0.85,
+        "medium": 0.65,
+        "low": 0.45,
+    }.get(str(priority or "medium").strip().lower(), 0.65)
+
+
+def _parse_timestamp(value) -> float:
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value or "").strip()
+    if not text:
+        return 0.0
+    try:
+        return float(text)
+    except Exception:
+        pass
+    for fmt in (None, "%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
+        try:
+            if fmt is None:
+                return datetime.fromisoformat(text.replace("Z", "+00:00")).timestamp()
+            return datetime.strptime(text, fmt).timestamp()
+        except Exception:
+            continue
+    return 0.0
+
+
+def _recency_score(row: dict) -> float:
+    reference = _parse_timestamp(row.get("last_guard_hit_at")) or _parse_timestamp(row.get("updated_at")) or _parse_timestamp(row.get("created_at"))
+    if not reference:
+        return 0.35
+    age_days = max(0.0, (now_epoch() - reference) / 86400.0)
+    if age_days <= 7:
+        return 1.0
+    if age_days <= 30:
+        return 0.8
+    if age_days <= 90:
+        return 0.6
+    if age_days <= 180:
+        return 0.4
+    return 0.25
+
+
+def _usefulness_score(row: dict) -> float:
+    hits = int(row.get("guard_hits") or 0)
+    if hits >= 5:
+        return 1.0
+    if hits >= 3:
+        return 0.85
+    if hits >= 1:
+        return 0.65
+    return 0.35 if str(row.get("status") or "active") == "active" else 0.15
+
+
+def _source_richness_score(row: dict) -> float:
+    parts = 0.0
+    if str(row.get("reasoning") or "").strip():
+        parts += 0.25
+    if str(row.get("prevention") or "").strip():
+        parts += 0.25
+    if str(row.get("applies_to") or "").strip():
+        parts += 0.2
+    if row.get("review_due_at"):
+        parts += 0.15
+    if len(str(row.get("content") or "").strip()) >= 80:
+        parts += 0.15
+    return min(1.0, parts)
+
+
+def _contradiction_pressure_score(conn, row: dict) -> float:
+    if str(row.get("status") or "active") != "active":
+        return 0.7
+    conflicting = _find_conflicting_active_learning(
+        conn,
+        category=str(row.get("category") or ""),
+        title=str(row.get("title") or ""),
+        content=str(row.get("content") or ""),
+        applies_to=str(row.get("applies_to") or ""),
+        exclude_id=int(row.get("id") or 0),
+    )
+    return 0.0 if conflicting else 1.0
+
+
+def score_learning_quality(row: dict, conn=None) -> dict:
+    """Compute a 0-100 quality score for a learning using usefulness and conflict pressure."""
+    conn = conn or get_db()
+    confidence = min(1.0, (_priority_score(row.get("priority")) * 0.45) + (float(row.get("weight") or 0.5) * 0.55))
+    usefulness = _usefulness_score(row)
+    recency = _recency_score(row)
+    contradiction = _contradiction_pressure_score(conn, row)
+    source_richness = _source_richness_score(row)
+    status = str(row.get("status") or "active")
+    status_multiplier = 1.0 if status == "active" else 0.65 if status in {"pending_review", "review"} else 0.45
+    overall = (
+        confidence * 0.28
+        + usefulness * 0.24
+        + recency * 0.18
+        + contradiction * 0.18
+        + source_richness * 0.12
+    ) * status_multiplier
+    score = max(0, min(100, round(overall * 100)))
+    if score >= 80:
+        label = "strong"
+    elif score >= 60:
+        label = "usable"
+    elif score >= 40:
+        label = "weak"
+    else:
+        label = "fragile"
+    return {
+        "score": score,
+        "label": label,
+        "confidence": round(confidence * 100),
+        "usefulness": round(usefulness * 100),
+        "recency_relevance": round(recency * 100),
+        "contradiction_pressure": round((1.0 - contradiction) * 100),
+        "source_richness": round(source_richness * 100),
+    }
+
 
 def handle_learning_add(category: str, title: str, content: str, reasoning: str = '',
                         prevention: str = '', applies_to: str = '', review_days: int = 30,
-                        priority: str = 'medium') -> str:
+                        priority: str = 'medium', supersedes_id: int = 0) -> str:
     """Add a new learning entry to the specified category.
 
     Args:
@@ -31,8 +287,21 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
     ).fetchone()
     if existing:
         return f"Learning #{existing['id']} already exists with same title in {category}: {existing['title']}. Use nexo_learning_update to modify it."
+    conflicting = _find_conflicting_active_learning(
+        conn,
+        category=category,
+        title=title,
+        content=content,
+        applies_to=applies_to,
+    )
+    if conflicting and int(supersedes_id or 0) != int(conflicting["id"]):
+        return (
+            f"ERROR: Contradictory active learning #{conflicting['id']} already exists for applies_to="
+            f"{conflicting.get('applies_to', '')}: {conflicting['title']}. "
+            f"Supersede or update the existing canonical rule instead of creating two active file rules."
+        )
     result = create_learning(
-        category, title, content, reasoning=reasoning
+        category, title, content, reasoning=reasoning, supersedes_id=(int(supersedes_id) if supersedes_id else None)
     )
     if "error" in result:
         return f"ERROR: {result['error']}"
@@ -102,11 +371,18 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
     except Exception:
         pass
 
+    if supersedes_id:
+        superseded = supersede_learning(int(supersedes_id), new_id, f"Superseded by learning #{new_id}.")
+        if "error" in superseded:
+            return f"ERROR: Learning #{new_id} created but supersede failed: {superseded['error']}"
+
     meta = []
     if prevention:
         meta.append("with prevention")
     if applies_to:
         meta.append(f"applies_to={applies_to}")
+    if supersedes_id:
+        meta.append(f"supersedes={int(supersedes_id)}")
     meta_str = f" ({', '.join(meta)})" if meta else ""
     return f"Learning #{result['id']} added in {category}: {title}{meta_str}{repetition_msg}"
 
@@ -117,6 +393,7 @@ def handle_learning_search(query: str, category: str = '') -> str:
     if not results:
         return f"No results for '{query}'."
     lines = [f"RESULTS ({len(results)}):"]
+    conn = get_db()
     for r in results:
         snippet = r["content"][:100] + "..." if len(r["content"]) > 100 else r["content"]
         status = r.get("status", "active")
@@ -124,8 +401,9 @@ def handle_learning_search(query: str, category: str = '') -> str:
         review_note = f" | review_due={review_due:.0f}" if isinstance(review_due, (int, float)) and review_due else ""
         pri = r.get("priority", "medium") or "medium"
         w = r.get("weight", 0.5) or 0.5
+        quality = score_learning_quality(r, conn)
         pri_icon = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "⚪"}.get(pri, "🟡")
-        lines.append(f"  #{r['id']} [{r['category']}] [{status}] {pri_icon}{pri} w={w:.2f} {r['title']}{review_note}")
+        lines.append(f"  #{r['id']} [{r['category']}] [{status}] {pri_icon}{pri} w={w:.2f} q={quality['score']} {r['title']}{review_note}")
         lines.append(f"    {snippet}")
         if r.get("prevention"):
             lines.append(f"    Prevention: {r['prevention'][:100]}")
@@ -143,8 +421,13 @@ def handle_learning_search(query: str, category: str = '') -> str:
 
 def handle_learning_update(id: int, title: str = '', content: str = '', category: str = '',
                            reasoning: str = '', prevention: str = '', applies_to: str = '',
-                           status: str = '', review_days: int = 0, priority: str = '') -> str:
+                           status: str = '', review_days: int = 0, priority: str = '',
+                           supersedes_id: int = 0) -> str:
     """Update an existing learning, including review metadata and priority."""
+    conn = get_db()
+    current = conn.execute("SELECT * FROM learnings WHERE id = ?", (id,)).fetchone()
+    if not current:
+        return f"ERROR: Learning #{id} not found."
     kwargs = {}
     if title:
         kwargs["title"] = title
@@ -164,6 +447,26 @@ def handle_learning_update(id: int, title: str = '', content: str = '', category
         kwargs["review_days"] = review_days
     if not kwargs:
         return "ERROR: Nothing to update. Provide new fields."
+    effective_category = kwargs.get("category", current["category"])
+    effective_title = kwargs.get("title", current["title"])
+    effective_content = kwargs.get("content", current["content"])
+    effective_applies_to = kwargs.get("applies_to", current["applies_to"])
+    effective_status = kwargs.get("status", current["status"])
+    if effective_status != "superseded":
+        conflicting = _find_conflicting_active_learning(
+            conn,
+            category=effective_category,
+            title=effective_title,
+            content=effective_content,
+            applies_to=effective_applies_to,
+            exclude_id=id,
+        )
+        if conflicting and int(supersedes_id or 0) != int(conflicting["id"]):
+            return (
+                f"ERROR: Update would conflict with active learning #{conflicting['id']} "
+                f"for applies_to={conflicting.get('applies_to', '')}. "
+                f"Supersede the old rule or merge into one canonical learning."
+            )
     basic_kwargs = {k: v for k, v in kwargs.items() if k in {"title", "content", "category", "reasoning"}}
     result = update_learning(id, **basic_kwargs)
     if "error" in result:
@@ -187,6 +490,10 @@ def handle_learning_update(id: int, title: str = '', content: str = '', category
         conn = get_db()
         conn.execute(f"UPDATE learnings SET {set_clause} WHERE id = ?", values)
         conn.commit()
+    if supersedes_id:
+        superseded = supersede_learning(int(supersedes_id), id, f"Superseded by learning #{id}.")
+        if "error" in superseded:
+            return f"ERROR: Learning #{id} updated but supersede failed: {superseded['error']}"
     return f"Learning #{id} updated."
 
 
@@ -205,14 +512,16 @@ def handle_learning_list(category: str = '') -> str:
         label = category if category else "ALL"
         return f"LEARNINGS {label} (0): No entries."
 
+    conn = get_db()
     if category:
         label = category.upper()
         lines = [f"LEARNINGS {label} ({len(results)}):"]
         for r in results:
             pri = r.get("priority", "medium") or "medium"
             w = r.get("weight", 0.5) or 0.5
+            quality = score_learning_quality(r, conn)
             pri_icon = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "⚪"}.get(pri, "🟡")
-            lines.append(f"  #{r['id']} [{r.get('status','active')}] {pri_icon}{pri} w={w:.2f} {r['title']}")
+            lines.append(f"  #{r['id']} [{r.get('status','active')}] {pri_icon}{pri} w={w:.2f} q={quality['score']} {r['title']}")
     else:
         lines = [f"LEARNINGS ALL ({len(results)}):"]
         current_cat = None
@@ -222,7 +531,36 @@ def handle_learning_list(category: str = '') -> str:
                 lines.append(f"\n  [{current_cat.upper()}]")
             pri = r.get("priority", "medium") or "medium"
             w = r.get("weight", 0.5) or 0.5
+            quality = score_learning_quality(r, conn)
             pri_icon = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "⚪"}.get(pri, "🟡")
-            lines.append(f"    #{r['id']} [{r.get('status','active')}] {pri_icon}{pri} w={w:.2f} {r['title']}")
+            lines.append(f"    #{r['id']} [{r.get('status','active')}] {pri_icon}{pri} w={w:.2f} q={quality['score']} {r['title']}")
+
+    return "\n".join(lines)
 
+
+def handle_learning_quality(id: int = 0, category: str = "", status: str = "active", limit: int = 20) -> str:
+    """Inspect memory quality so fragile learnings can be tightened before they mislead guard/retrieval."""
+    results = list_learnings(category if category else None)
+    if id:
+        results = [row for row in results if int(row.get("id") or 0) == int(id)]
+    if status:
+        results = [row for row in results if str(row.get("status") or "").lower() == str(status).lower()]
+    results = results[: max(1, int(limit or 20))]
+    if not results:
+        return "LEARNING QUALITY (0): No matching learnings."
+
+    conn = get_db()
+    scored = []
+    for row in results:
+        quality = score_learning_quality(row, conn)
+        scored.append((row, quality))
+    avg_score = round(sum(item[1]["score"] for item in scored) / len(scored))
+    weak = [item for item in scored if item[1]["score"] < 60]
+    lines = [f"LEARNING QUALITY ({len(scored)}) avg={avg_score} weak={len(weak)}:"]
+    for row, quality in scored:
+        lines.append(
+            f"  #{row['id']} q={quality['score']} [{quality['label']}] {row['title']} "
+            f"(conf={quality['confidence']} useful={quality['usefulness']} recency={quality['recency_relevance']} "
+            f"pressure={quality['contradiction_pressure']} richness={quality['source_richness']})"
+        )
     return "\n".join(lines)

package/src/tools_sessions.py

@@ -1,15 +1,20 @@
 from __future__ import annotations
 """Session management tools: startup, heartbeat, status."""
 
+import json
+import os
 import time
 import secrets
 import threading
+from datetime import datetime, UTC
+from pathlib import Path
 from db import (
     register_session, update_session, complete_session,
     get_active_sessions, clean_stale_sessions, search_sessions,
     get_inbox, get_pending_questions, now_epoch,
     SESSION_STALE_SECONDS, check_session_has_diary,
     save_checkpoint, read_checkpoint, increment_compaction_count,
+    get_db,
 )
 
 # ── Session Keepalive ────────────────────────────────────────────────
@@ -19,6 +24,8 @@ from db import (
 # Threads are daemon=True so they die when the MCP server process exits.
 
 KEEPALIVE_INTERVAL = 600  # 10 min — well inside the 15-min TTL
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+SESSION_PORTABILITY_DIR = NEXO_HOME / "operations" / "session-portability"
 
 _keepalive_threads: dict[str, threading.Event] = {}  # sid → stop_event
 
@@ -64,6 +71,182 @@ def _format_age(epoch: float) -> str:
         return f"{int(seconds / 3600)}h{int((seconds % 3600) / 60)}m"
 
 
+def _resolve_session_row(conn, sid: str = ""):
+    if sid.strip():
+        return conn.execute("SELECT * FROM sessions WHERE sid = ?", (sid.strip(),)).fetchone()
+    return conn.execute(
+        "SELECT * FROM sessions ORDER BY last_update_epoch DESC LIMIT 1"
+    ).fetchone()
+
+
+def _session_portability_bundle(sid: str = "") -> dict:
+    conn = get_db()
+    session_row = _resolve_session_row(conn, sid)
+    if not session_row:
+        return {"ok": False, "error": "session not found"}
+
+    session_id = str(session_row["sid"])
+    checkpoint = read_checkpoint(session_id) or {}
+    diary = conn.execute(
+        """SELECT summary, decisions, pending, context_next, mental_state, domain, created_at
+           FROM session_diary
+           WHERE session_id = ?
+           ORDER BY created_at DESC
+           LIMIT 1""",
+        (session_id,),
+    ).fetchone()
+    draft = conn.execute(
+        """SELECT summary_draft, last_context_hint, updated_at
+           FROM session_diary_draft
+           WHERE sid = ?""",
+        (session_id,),
+    ).fetchone()
+    protocol_tasks = [
+        dict(row) for row in conn.execute(
+            """SELECT task_id, goal, task_type, area, status, opened_at
+               FROM protocol_tasks
+               WHERE session_id = ? AND status = 'open'
+               ORDER BY opened_at DESC
+               LIMIT 10""",
+            (session_id,),
+        ).fetchall()
+    ]
+    workflow_goals = [
+        dict(row) for row in conn.execute(
+            """SELECT goal_id, title, status, priority, next_action, blocker_reason, updated_at
+               FROM workflow_goals
+               WHERE session_id = ? AND status IN ('active', 'blocked')
+               ORDER BY updated_at DESC
+               LIMIT 10""",
+            (session_id,),
+        ).fetchall()
+    ]
+    workflow_runs = [
+        dict(row) for row in conn.execute(
+            """SELECT run_id, goal_id, goal, workflow_kind, status, priority, next_action, current_step_key, updated_at
+               FROM workflow_runs
+               WHERE session_id = ? AND status IN ('open', 'running', 'blocked', 'needs_approval')
+               ORDER BY updated_at DESC
+               LIMIT 10""",
+            (session_id,),
+        ).fetchall()
+    ]
+    return {
+        "ok": True,
+        "generated_at": datetime.now(UTC).isoformat(),
+        "session": {
+            "sid": session_id,
+            "task": session_row["task"],
+            "client": session_row["session_client"],
+            "external_session_id": session_row["external_session_id"],
+            "started_epoch": session_row["started_epoch"],
+            "last_update_epoch": session_row["last_update_epoch"],
+            "local_time": session_row["local_time"],
+        },
+        "checkpoint": dict(checkpoint) if checkpoint else {},
+        "latest_diary": dict(diary) if diary else {},
+        "diary_draft": dict(draft) if draft else {},
+        "open_protocol_tasks": protocol_tasks,
+        "open_workflow_goals": workflow_goals,
+        "open_workflow_runs": workflow_runs,
+    }
+
+
+def handle_session_portable_context(sid: str = "") -> str:
+    """Build a portable handoff packet for another client/runtime."""
+    bundle = _session_portability_bundle(sid)
+    if not bundle.get("ok"):
+        return f"ERROR: {bundle.get('error', 'session not found')}"
+
+    session = bundle["session"]
+    checkpoint = bundle.get("checkpoint") or {}
+    diary = bundle.get("latest_diary") or {}
+    draft = bundle.get("diary_draft") or {}
+    lines = [
+        "SESSION PORTABILITY PACKET",
+        f"SID: {session['sid']}",
+        f"Task: {session['task'] or '(none)'}",
+        f"Client: {session['client'] or '(unknown)'}",
+    ]
+    if session.get("external_session_id"):
+        lines.append(f"External session: {session['external_session_id']}")
+    if checkpoint:
+        lines.extend(
+            [
+                "",
+                "Checkpoint:",
+                f"- Goal: {checkpoint.get('current_goal') or checkpoint.get('task') or '(none)'}",
+                f"- Next: {checkpoint.get('next_step') or '(none)'}",
+                f"- Files: {checkpoint.get('active_files') or '[]'}",
+            ]
+        )
+    if diary:
+        lines.extend(
+            [
+                "",
+                "Latest diary:",
+                f"- Summary: {diary.get('summary') or '(none)'}",
+                f"- Pending: {diary.get('pending') or '(none)'}",
+                f"- Context next: {diary.get('context_next') or '(none)'}",
+            ]
+        )
+    elif draft:
+        lines.extend(
+            [
+                "",
+                "Diary draft:",
+                f"- Summary draft: {draft.get('summary_draft') or '(none)'}",
+                f"- Context hint: {draft.get('last_context_hint') or '(none)'}",
+            ]
+        )
+
+    protocol_tasks = bundle.get("open_protocol_tasks") or []
+    if protocol_tasks:
+        lines.extend(["", "Open protocol tasks:"])
+        for item in protocol_tasks[:5]:
+            lines.append(f"- {item['task_id']}: {item['goal']} [{item['task_type']}/{item['status']}]")
+
+    goals = bundle.get("open_workflow_goals") or []
+    if goals:
+        lines.extend(["", "Open goals:"])
+        for item in goals[:5]:
+            lines.append(f"- {item['goal_id']}: {item['title']} [{item['status']}] -> {item['next_action'] or '(no next action)'}")
+
+    runs = bundle.get("open_workflow_runs") or []
+    if runs:
+        lines.extend(["", "Open workflows:"])
+        for item in runs[:5]:
+            lines.append(
+                f"- {item['run_id']}: {item['goal']} [{item['status']}] "
+                f"step={item['current_step_key'] or '?'} next={item['next_action'] or '(none)'}"
+            )
+
+    return "\n".join(lines)
+
+
+def handle_session_export_bundle(sid: str = "", path: str = "") -> str:
+    """Export a machine-readable session bundle for cross-client handoff."""
+    bundle = _session_portability_bundle(sid)
+    if not bundle.get("ok"):
+        return json.dumps(bundle, ensure_ascii=False)
+
+    session_id = bundle["session"]["sid"]
+    export_path = Path(path).expanduser() if path else (SESSION_PORTABILITY_DIR / f"{session_id}.json")
+    export_path.parent.mkdir(parents=True, exist_ok=True)
+    export_path.write_text(json.dumps(bundle, indent=2, ensure_ascii=False) + "\n")
+    return json.dumps(
+        {
+            "ok": True,
+            "sid": session_id,
+            "path": str(export_path),
+            "open_protocol_tasks": len(bundle.get("open_protocol_tasks") or []),
+            "open_workflow_goals": len(bundle.get("open_workflow_goals") or []),
+            "open_workflow_runs": len(bundle.get("open_workflow_runs") or []),
+        },
+        ensure_ascii=False,
+    )
+
+
 def handle_startup(
     task: str = "Startup",
     claude_session_id: str = "",

package/templates/CLAUDE.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-claude-md-version: 2.0.0 -->
+<!-- nexo-claude-md-version: 2.1.2 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
@@ -20,6 +20,14 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 **Presentation:** {{NAME}} speaks first. Conversational greeting adapted to time of day. Tell what you HAVE DONE, not list pending items. Menu only if the user asks.
 <!-- nexo:end:startup -->
 
+## Protocol (6 rules)
+1. `nexo_startup` once per session and keep the returned `SID`.
+2. `nexo_heartbeat` on every user message.
+3. `nexo_task_open` for any non-trivial work. For `edit` / `execute` / `delegate`, this is the default path. If the work is long multi-step or likely to cross messages/sessions, also open `nexo_workflow_open` and keep it updated. If task_open surfaces blocking conditioned-file learnings, review them and acknowledge guard before any write / delete step.
+4. Do not say `done`, `fixed`, or `sent` without evidence captured in `nexo_task_close`.
+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.
+
 <!-- nexo:start:profile -->
 ## User Profile
 - **Calibration:** `{{NEXO_HOME}}/brain/calibration.json` (personality settings + language + user name)