nexo-brain 5.3.19 → 5.3.21

package/src/hooks/auto_capture 2.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""NEXO Auto-Capture Hook — Extract facts from conversation context.
+
+Inspired by claude-mem's observation handler and transcript processor.
+Uses simple heuristics (no LLM) to extract decisions, corrections,
+and explicit facts from conversation messages.
+
+Can be called:
+- Programmatically via process_conversation()
+- From Claude Code hooks via stdin (pipe conversation lines)
+- As CLI: python3 auto_capture.py "message1" "message2" ...
+
+Stores extracted facts via cognitive.ingest() with appropriate tags.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+# Add source dir to path for cognitive imports
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+import cognitive
+
+
+# ---------------------------------------------------------------------------
+# Pattern definitions (adapted from claude-mem's transcript processor
+# and ShieldCortex's pattern groups approach)
+# ---------------------------------------------------------------------------
+
+# Decision patterns — lines indicating a choice was made
+_DECISION_PATTERNS = [
+    re.compile(r'\b(?:decided|agreed|will do|changed to|switching to|going with|chose|chosen|opted for)\b', re.IGNORECASE),
+    re.compile(r'\b(?:let\'?s go with|the plan is|we\'?ll use|moving forward with)\b', re.IGNORECASE),
+    re.compile(r'\b(?:approved|confirmed|locked in|finalized)\b', re.IGNORECASE),
+    re.compile(r'\b(?:decidido|acordado|vamos con|cambiamos a|elegimos)\b', re.IGNORECASE),  # Spanish
+]
+
+# Correction patterns — lines indicating something was wrong
+_CORRECTION_PATTERNS = [
+    re.compile(r'\b(?:don\'?t|stop|wrong|incorrect|that\'?s not right|fix this)\b', re.IGNORECASE),
+    re.compile(r'\b(?:should be|actually|not that|the correct|mistake|error)\b', re.IGNORECASE),
+    re.compile(r'\b(?:never do that|wrong approach|that broke|revert)\b', re.IGNORECASE),
+    re.compile(r'\b(?:no,\s|nope|mal|otra vez|ya te dije|no es|est[aá] mal)\b', re.IGNORECASE),  # Spanish
+]
+
+# Explicit fact patterns — user explicitly asks to remember something
+_EXPLICIT_PATTERNS = [
+    re.compile(r'\b(?:remember|note that|important:|keep in mind|don\'?t forget)\b', re.IGNORECASE),
+    re.compile(r'\b(?:for future reference|take note|key point|rule:)\b', re.IGNORECASE),
+    re.compile(r'\b(?:recuerda|importante:|ten en cuenta|no olvides|regla:)\b', re.IGNORECASE),  # Spanish
+]
+
+# Minimum line length to consider (skip very short lines)
+_MIN_LINE_LENGTH = 15
+
+# Maximum fact content length
+_MAX_FACT_LENGTH = 500
+
+
+def _classify_line(line: str) -> list[tuple[str, str]]:
+    """Classify a single line into fact types.
+
+    Returns list of (fact_type, content) tuples. A line can match
+    multiple categories.
+    """
+    line = line.strip()
+    if len(line) < _MIN_LINE_LENGTH:
+        return []
+
+    facts = []
+
+    for pattern in _DECISION_PATTERNS:
+        if pattern.search(line):
+            facts.append(("decision", line))
+            break
+
+    for pattern in _CORRECTION_PATTERNS:
+        if pattern.search(line):
+            facts.append(("correction", line))
+            break
+
+    for pattern in _EXPLICIT_PATTERNS:
+        if pattern.search(line):
+            facts.append(("explicit", line))
+            break
+
+    return facts
+
+
+def process_conversation(messages: list[str]) -> dict:
+    """Process conversation messages and extract key facts.
+
+    Adapted from claude-mem's TranscriptEventProcessor: scans each message
+    line for decision, correction, and explicit fact patterns. Stores
+    extracted facts via cognitive.ingest() with source_type='auto_capture'.
+
+    Args:
+        messages: List of conversation message strings
+
+    Returns:
+        Dict with facts_extracted, decisions, corrections, stored,
+        rejected_by_gate counts and extracted_facts details.
+    """
+    all_facts = []
+    decisions = 0
+    corrections = 0
+    explicits = 0
+
+    for msg in messages:
+        # Split message into lines and classify each
+        for line in msg.split("\n"):
+            classified = _classify_line(line)
+            for fact_type, content in classified:
+                if fact_type == "decision":
+                    decisions += 1
+                elif fact_type == "correction":
+                    corrections += 1
+                elif fact_type == "explicit":
+                    explicits += 1
+                all_facts.append((fact_type, content[:_MAX_FACT_LENGTH]))
+
+    # Deduplicate by content (same line might appear in multiple messages)
+    seen = set()
+    unique_facts = []
+    for fact_type, content in all_facts:
+        content_key = content.lower().strip()
+        if content_key not in seen:
+            seen.add(content_key)
+            unique_facts.append((fact_type, content))
+
+    # Store via cognitive.ingest()
+    stored = 0
+    rejected_by_gate = 0
+    extracted_details = []
+
+    for fact_type, content in unique_facts:
+        # Build tagged content for better retrieval
+        tagged_content = f"[{fact_type.upper()}] {content}"
+
+        result_id = cognitive.ingest(
+            content=tagged_content,
+            source_type="auto_capture",
+            source_id=f"hook_{fact_type}",
+            source_title=f"Auto-captured {fact_type}",
+            domain="conversation",
+            source="agent_observation",
+            skip_quarantine=False,  # Route through quarantine for safety
+            bypass_gate=False,      # Let prediction error gate filter duplicates
+        )
+
+        if result_id == 0:
+            rejected_by_gate += 1
+        else:
+            stored += 1
+
+        extracted_details.append({
+            "type": fact_type,
+            "content": content[:100],
+            "stored": result_id != 0,
+            "memory_id": result_id,
+        })
+
+    return {
+        "facts_extracted": len(unique_facts),
+        "decisions": decisions,
+        "corrections": corrections,
+        "explicits": explicits,
+        "stored": stored,
+        "rejected_by_gate": rejected_by_gate,
+        "extracted_facts": extracted_details,
+    }
+
+
+def _read_stdin() -> list[str]:
+    """Read conversation lines from stdin (for hook integration)."""
+    if sys.stdin.isatty():
+        return []
+    return [line for line in sys.stdin.read().strip().split("\n") if line.strip()]
+
+
+def main():
+    """CLI entry point — accepts messages as args or from stdin.
+
+    Usage:
+        echo "We decided to use PostgreSQL" | python3 auto_capture.py
+        python3 auto_capture.py "Remember: always use WAL mode" "That's wrong, fix it"
+    """
+    messages = list(sys.argv[1:]) if len(sys.argv) > 1 else _read_stdin()
+
+    if not messages:
+        print("Usage: python3 auto_capture.py 'message1' 'message2' ...")
+        print("   or: echo 'messages' | python3 auto_capture.py")
+        sys.exit(1)
+
+    result = process_conversation(messages)
+    print(f"Facts extracted: {result['facts_extracted']}")
+    print(f"  Decisions: {result['decisions']}")
+    print(f"  Corrections: {result['corrections']}")
+    print(f"  Explicits: {result['explicits']}")
+    print(f"Stored: {result['stored']}, Rejected by gate: {result['rejected_by_gate']}")
+
+    for fact in result["extracted_facts"]:
+        status = "STORED" if fact["stored"] else "REJECTED"
+        print(f"  [{status}] [{fact['type']}] {fact['content']}")
+
+
+if __name__ == "__main__":
+    main()

package/src/hooks/caffeinate-guard 2.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# NEXO Caffeinate Guard — keeps the Mac awake so nocturnal processes run on schedule.
+# Runs as a LaunchAgent with KeepAlive=true. If killed, launchd restarts it.
+#
+# Uses the native macOS caffeinate helper. Closed-lid behavior remains
+# best-effort and depends on the host setup.
+
+exec /usr/bin/caffeinate -d -i -m -s /bin/bash -lc 'while :; do sleep 3600; done'

package/src/hooks/capture-session 2.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# NEXO PostToolUse hook — captures tool usage to session_buffer.jsonl
+# This feeds the Sensory Register (Atkinson-Shiffrin Layer 1)
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+BUFFER="$NEXO_HOME/brain/session_buffer.jsonl"
+
+mkdir -p "$NEXO_HOME/brain"
+
+# Capture basic event: timestamp + tool name
+# Read stdin (Claude Code passes JSON via stdin for PostToolUse hooks)
+INPUT=$(cat 2>/dev/null || true)
+TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%S")
+
+# Only log meaningful tool calls (skip reads, globs, greps)
+case "$TOOL_NAME" in
+    Read|Glob|Grep|LS|Bash) exit 0 ;;
+esac
+
+echo "{\"ts\":\"$TS\",\"tool\":\"$TOOL_NAME\",\"source\":\"hook\"}" >> "$BUFFER"

package/src/hooks/capture-tool-logs 2.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# NEXO PostToolUse hook — persists tool call outputs to daily JSONL logs
+# Fires automatically after every successful or failed tool use.
+# Logs survive context compactions.
+# Auto-cleanup: deletes logs >= 30 days old.
+# Optimized: skips read-only tools (Read, Grep, Glob, LS, Skill, ToolSearch).
+
+# Read full JSON from stdin first
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+# Extract tool_name early and exit if read-only (avoids overhead on 90%+ of calls)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || true)
+
+case "$TOOL_NAME" in
+    Read|Grep|Glob|LS|Skill|ToolSearch) exit 0 ;;
+esac
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+LOG_DIR="$NEXO_HOME/operations/tool-logs"
+mkdir -p "$LOG_DIR"
+
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$LOG_DIR/${TODAY}.jsonl"
+
+# Build and write record with python3 (faster than jq on macOS when cached)
+# Security: redact output of credential-related tools to avoid plaintext secrets in logs
+echo "$INPUT" | python3 -c "
+import json, sys, re
+from datetime import datetime
+d = json.load(sys.stdin)
+tool_name = d.get('tool_name', 'unknown')
+
+tool_input = d.get('tool_input')
+tool_response = d.get('tool_response')
+
+# Redact tools that handle credentials/secrets
+SENSITIVE_TOOLS = ('credential', 'secret', 'token', 'password', 'apikey', 'api_key')
+if any(kw in tool_name.lower() for kw in SENSITIVE_TOOLS):
+    tool_response = '[REDACTED]'
+    # Also redact input values (keep keys for debuggability)
+    if isinstance(tool_input, dict):
+        tool_input = {k: '[REDACTED]' if k not in ('servicio', 'service', 'name', 'key') else v for k, v in tool_input.items()}
+
+record = {
+    'timestamp': datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
+    'session_id': d.get('session_id', 'unknown'),
+    'tool_name': tool_name,
+    'hook_event': d.get('hook_event_name', 'unknown'),
+    'tool_use_id': d.get('tool_use_id'),
+    'tool_input': tool_input,
+    'tool_response': tool_response,
+    'error': d.get('error')
+}
+print(json.dumps(record))
+" >> "$LOG_FILE" 2>/dev/null
+
+# ── Layer 1: Auto-diary every 10 tool calls (session-scoped) ─────────
+# Extract session_id for per-session counters (prevents cross-terminal contamination)
+SESSION_ID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id','global'))" 2>/dev/null || echo "global")
+COUNTER_DIR="$NEXO_HOME/operations/counters"
+mkdir -p "$COUNTER_DIR"
+COUNTER_FILE="$COUNTER_DIR/.tool-call-count-${SESSION_ID}"
+NEXO_DB="$NEXO_HOME/data/nexo.db"
+
+# Increment counter (atomic: read+write in one step)
+COUNT=1
+if [ -f "$COUNTER_FILE" ]; then
+    COUNT=$(( $(cat "$COUNTER_FILE" 2>/dev/null || echo 0) + 1 ))
+fi
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Every 10 tool calls, write a mechanical diary draft to SQLite
+if [ $(( COUNT % 10 )) -eq 0 ] && [ -f "$NEXO_DB" ]; then
+    python3 -c "
+import json, sqlite3, os, sys
+from datetime import datetime
+
+db_path = '$NEXO_DB'
+log_file = '$LOG_FILE'
+count = $COUNT
+
+# Read last 10 tool calls from today's log
+entries = []
+if os.path.isfile(log_file):
+    with open(log_file, 'r') as f:
+        lines = f.readlines()
+        for line in lines[-10:]:
+            try:
+                e = json.loads(line.strip())
+                name = e.get('tool_name', '?')
+                inp = e.get('tool_input', {})
+                # Brief args: first key's value, truncated
+                brief = ''
+                if isinstance(inp, dict):
+                    for k, v in list(inp.items())[:1]:
+                        brief = str(v)[:60]
+                entries.append(f'{name}({brief})')
+            except Exception:
+                pass
+
+if not entries:
+    sys.exit(0)
+
+tools_summary = ', '.join(entries[-10:])
+
+# Get session by claude session_id (scoped), fallback to most recent
+session_id = '$SESSION_ID'
+conn = sqlite3.connect(db_path, timeout=2)
+conn.row_factory = sqlite3.Row
+
+# Try to find NEXO SID mapped to this claude session_id
+row = None
+if session_id and session_id != 'global':
+    row = conn.execute(
+        'SELECT sid, task FROM sessions WHERE external_session_id = ? OR claude_session_id = ? LIMIT 1',
+        (session_id, session_id)
+    ).fetchone()
+
+# Fallback: most recent active session
+if not row:
+    row = conn.execute(
+        'SELECT sid, task FROM sessions ORDER BY last_update_epoch DESC LIMIT 1'
+    ).fetchone()
+
+if not row:
+    conn.close()
+    sys.exit(0)
+
+sid = row['sid']
+task = row['task'] or 'unknown'
+
+summary = f'[AUTO-{count}] {len(entries)} tool calls: {tools_summary[:250]}. Task: {task[:100]}'
+
+# Write to session_diary_draft (UPSERT)
+conn.execute('''
+    INSERT INTO session_diary_draft (sid, summary_draft, tasks_seen, change_ids, decision_ids, last_context_hint, heartbeat_count, updated_at)
+    VALUES (?, ?, '[]', '[]', '[]', ?, 0, datetime('now'))
+    ON CONFLICT(sid) DO UPDATE SET
+        summary_draft = excluded.summary_draft,
+        last_context_hint = excluded.last_context_hint,
+        updated_at = datetime('now')
+''', (sid, summary, f'auto-diary at {count} tool calls'))
+conn.commit()
+conn.close()
+" 2>/dev/null &
+    # Reset counter after writing
+    echo "0" > "$COUNTER_FILE"
+fi
+
+# Cleanup: delete logs >= 30 days old (once daily, uses marker file)
+CLEANUP_MARKER="$LOG_DIR/.last-cleanup"
+if [ ! -f "$CLEANUP_MARKER" ] || [ "$(cat "$CLEANUP_MARKER" 2>/dev/null)" != "$TODAY" ]; then
+    find "$LOG_DIR" -name "*.jsonl" -mtime +30 -delete 2>/dev/null || true
+    echo "$TODAY" > "$CLEANUP_MARKER"
+fi
+
+exit 0

package/src/hooks/daily-briefing-check 2.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# NEXO Daily Briefing — SessionStart hook
+# Checks if a briefing should be sent and creates a flag for NEXO to process.
+# Does NOT send the email directly (needs Claude to research news).
+# Only marks that NEXO should launch the briefing at startup.
+# Frequency: Monday, Wednesday, Friday (3x/week)
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+BRIEFING_FILE="$NEXO_HOME/operations/.briefing-last-sent"
+FLAG_FILE="$NEXO_HOME/operations/.briefing-pending"
+TODAY=$(date +%Y-%m-%d)
+HOUR=$(date +%H)
+DOW=$(date +%u)  # 1=Monday, 7=Sunday
+
+# Only after 8:00 AM — before that counts as "previous day"
+if [ "$HOUR" -lt 8 ]; then
+    exit 0
+fi
+
+# Only Monday (1), Wednesday (3), Friday (5)
+if [ "$DOW" != "1" ] && [ "$DOW" != "3" ] && [ "$DOW" != "5" ]; then
+    exit 0
+fi
+
+# If already sent today, skip
+LAST_SENT=$(cat "$BRIEFING_FILE" 2>/dev/null)
+if [ "$LAST_SENT" = "$TODAY" ]; then
+    exit 0
+fi
+
+# Mark briefing as pending for NEXO to launch in background
+echo "$TODAY" > "$FLAG_FILE"
+echo "briefing-pending"

package/src/hooks/heartbeat-enforcement 2.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Heartbeat enforcement for NEXO sessions.
+
+Tracks user messages vs heartbeat calls. Emits a warning when more than two
+user messages pass without a heartbeat call.
+
+Modes:
+- HEARTBEAT_MODE=user_msg: increment counter on UserPromptSubmit
+- HEARTBEAT_MODE=post_tool: inspect PostToolUse payload, reset on heartbeat,
+  warn when other tools keep running without one
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+STATE_FILE = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo")) / "operations" / ".heartbeat-state.json"
+THRESHOLD = 2
+HEARTBEAT_TOOL = "nexo_heartbeat"
+SKIP_TOOLS = {"nexo_startup", "nexo_stop", "nexo_smart_startup"}
+
+
+def _read_state() -> dict:
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except Exception:
+        return {"user_msgs": 0, "last_heartbeat_ts": 0.0, "last_user_msg_ts": 0.0}
+
+
+def _write_state(state: dict) -> None:
+    try:
+        STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(json.dumps(state))
+    except Exception:
+        pass
+
+
+def handle_user_message() -> int:
+    state = _read_state()
+    state["user_msgs"] = state.get("user_msgs", 0) + 1
+    state["last_user_msg_ts"] = time.time()
+    _write_state(state)
+    return 0
+
+
+def handle_post_tool(payload: dict) -> int:
+    tool_name = str(payload.get("tool_name", "")).strip()
+    short_name = tool_name.rsplit("__", 1)[-1] if "__" in tool_name else tool_name
+    state = _read_state()
+
+    if short_name == HEARTBEAT_TOOL:
+        state["user_msgs"] = 0
+        state["last_heartbeat_ts"] = time.time()
+        _write_state(state)
+        return 0
+
+    if short_name in SKIP_TOOLS:
+        return 0
+
+    user_msgs = state.get("user_msgs", 0)
+    if user_msgs > THRESHOLD:
+        print(
+            f"\nWARNING: HEARTBEAT OVERDUE ({user_msgs} user messages without nexo_heartbeat). "
+            "Call nexo_heartbeat(sid=SID, task='...') before continuing."
+        )
+    return 0
+
+
+def main() -> int:
+    mode = os.environ.get("HEARTBEAT_MODE", "").strip()
+    if mode == "user_msg":
+        return handle_user_message()
+    if mode == "post_tool":
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return 0
+        try:
+            payload = json.loads(raw)
+        except Exception:
+            return 0
+        return handle_post_tool(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/hooks/heartbeat-posttool 2.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# NEXO PostToolUse hook — heartbeat enforcement checker
+set -uo pipefail
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+HELPER=""
+if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="${NEXO_CODE%/}/hooks/heartbeat-enforcement.py"
+elif [ -f "$NEXO_HOME/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="$NEXO_HOME/hooks/heartbeat-enforcement.py"
+fi
+
+[ -z "$HELPER" ] && exit 0
+HEARTBEAT_MODE=post_tool python3 "$HELPER" <<< "$INPUT" 2>/dev/null || true
+exit 0

package/src/hooks/inbox-hook 2.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# NEXO PostToolUse hook — automatic inter-terminal inbox check
+#
+# Zero output when no messages = zero tokens consumed in Claude's context.
+# Reads SQLite directly (no MCP overhead). Write-only: INSERT OR IGNORE for mark-as-read.
+# Debounce: skips if last check was <2 seconds ago.
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+# 1. Skip read-only tools (same logic as capture-tool-logs.sh)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || true)
+case "$TOOL_NAME" in
+    Read|Grep|Glob|LS|Skill|ToolSearch|Agent) exit 0 ;;
+esac
+
+# 2. Extract Claude Code session_id
+CLAUDE_SID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null)
+[ -z "$CLAUDE_SID" ] && exit 0
+
+# 3. Debounce: skip if last check <2s ago
+DEBOUNCE_FILE="/tmp/nexo-inbox-ts-${CLAUDE_SID}"
+NOW=$(date +%s)
+LAST=$(cat "$DEBOUNCE_FILE" 2>/dev/null || echo 0)
+DIFF=$((NOW - LAST))
+[ "$DIFF" -lt 2 ] && exit 0
+echo "$NOW" > "$DEBOUNCE_FILE"
+
+# 4. Find NEXO SID mapped to this Claude session_id
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+DB="$NEXO_HOME/data/nexo.db"
+mkdir -p "$NEXO_HOME/data"
+[ -f "$DB" ] || exit 0
+
+NEXO_SID=$(sqlite3 "$DB" "SELECT sid FROM sessions WHERE (external_session_id = '${CLAUDE_SID}' OR claude_session_id = '${CLAUDE_SID}') AND last_update_epoch > (strftime('%s','now') - 900) ORDER BY last_update_epoch DESC LIMIT 1;" 2>/dev/null)
+[ -z "$NEXO_SID" ] && exit 0
+
+# 5. Check inbox — messages addressed to this session or broadcast
+MESSAGES=$(sqlite3 -separator '|' "$DB" "
+    SELECT m.id, m.from_sid, m.text FROM messages m
+    WHERE (m.to_sid = 'all' OR m.to_sid = '${NEXO_SID}')
+    AND m.from_sid != '${NEXO_SID}'
+    AND m.id NOT IN (SELECT message_id FROM message_reads WHERE sid = '${NEXO_SID}')
+    LIMIT 5;
+" 2>/dev/null)
+
+# 6. Check pending questions
+QUESTIONS=$(sqlite3 -separator '|' "$DB" "
+    SELECT qid, from_sid, question FROM questions
+    WHERE to_sid = '${NEXO_SID}' AND answer IS NULL
+    LIMIT 3;
+" 2>/dev/null)
+
+# 7. If empty -> silent exit (0 tokens consumed)
+[ -z "$MESSAGES" ] && [ -z "$QUESTIONS" ] && exit 0
+
+# 8. Format and output (injected into Claude's context)
+echo ""
+echo "INTER-TERMINAL MESSAGE (auto-detected):"
+
+if [ -n "$MESSAGES" ]; then
+    echo "$MESSAGES" | while IFS='|' read -r mid from text; do
+        echo "  [$from]: $text"
+        # Mark as read (lightweight INSERT, WAL mode, no lock contention)
+        sqlite3 "$DB" "INSERT OR IGNORE INTO message_reads (message_id, sid) VALUES ('${mid}', '${NEXO_SID}');" 2>/dev/null
+    done
+fi
+
+if [ -n "$QUESTIONS" ]; then
+    echo "  PENDING QUESTIONS from another terminal — respond with nexo_answer:"
+    echo "$QUESTIONS" | while IFS='|' read -r qid from question; do
+        echo "  Q[$qid] from [$from]: $question"
+    done
+fi
+
+exit 0