nexo-brain 5.3.19 → 5.3.21

package/src/scripts/nexo-cognitive-decay 2.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""NEXO Cognitive Decay — Daily Ebbinghaus sweep + STM→LTM promotion."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+# Auto-detect: if running from repo (src/scripts/), use src/ as NEXO_CODE
+_script_dir = Path(__file__).resolve().parent
+_repo_src = _script_dir.parent  # src/scripts/ -> src/
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(_repo_src) if (_repo_src / "server.py").exists() else str(NEXO_HOME)))
+from datetime import datetime, timedelta
+
+sys.path.insert(0, str(NEXO_CODE))
+import cognitive
+
+STATE_FILE = NEXO_HOME / "operations" / ".catchup-state.json"
+
+
+CORRECTION_FATIGUE_FOLLOWUP_ID = "NF-CORRECTION-FATIGUE"
+
+
+def _open_correction_fatigue_followup(fatigued: list) -> str:
+    """Surface fatigued memories as a single high-priority followup.
+
+    Closes Fase 3 item 4 of NEXO-AUDIT-2026-04-11. check_correction_fatigue
+    already auto-decays the strength of memories corrected 3+ times in a
+    week and tags them under_review, but the under_review tag is never
+    read elsewhere — the user could lose hours debugging a wrong memory
+    before noticing it had been silently decayed. This helper writes a
+    single deterministic followup so the operator sees the list at the
+    next morning briefing.
+
+    Idempotent across daily runs via the fixed id NF-CORRECTION-FATIGUE
+    (INSERT OR REPLACE). Best-effort: never raises.
+    """
+    import sqlite3 as _sqlite3
+    if not fatigued:
+        return "no_signal"
+
+    db_path = (
+        os.environ.get("NEXO_TEST_DB")
+        or os.environ.get("NEXO_DB")
+        or str(NEXO_HOME / "data" / "nexo.db")
+    )
+    if not Path(db_path).exists():
+        return "skipped_no_db"
+
+    lines = [
+        f"NEXO detected {len(fatigued)} memory/memories corrected 3+ times in the last 7 days.",
+        "These have been auto-decayed to strength <= 0.2 and tagged under_review.",
+        "Verify each one and either delete it, refine its content, or accept the decay.",
+        "",
+    ]
+    for f in fatigued[:10]:
+        lines.append(
+            f"- LTM #{f.get('memory_id')} ({f.get('corrections_7d')}x corrections, "
+            f"strength={f.get('strength')}): {(f.get('content') or '')[:160]}"
+        )
+    if len(fatigued) > 10:
+        lines.append(f"... and {len(fatigued) - 10} more")
+    description = "\n".join(lines)
+    verification = (
+        "sqlite3 ~/.nexo/data/cognitive.db \"SELECT id, content, strength, tags "
+        "FROM ltm_memories WHERE tags LIKE '%under_review%' ORDER BY strength ASC LIMIT 50\""
+    )
+    now_epoch = datetime.now().timestamp()
+
+    conn = _sqlite3.connect(db_path)
+    try:
+        conn.execute(
+            "INSERT OR REPLACE INTO followups (id, description, date, status, "
+            "verification, created_at, updated_at, priority) "
+            "VALUES (?, ?, NULL, 'PENDING', ?, ?, ?, 'high')",
+            (CORRECTION_FATIGUE_FOLLOWUP_ID, description, verification, now_epoch, now_epoch),
+        )
+        conn.commit()
+    except Exception as e:
+        return f"failed: {e}"
+    finally:
+        conn.close()
+    return "opened_or_refreshed"
+
+
+def update_catchup_state():
+    """Register successful run so catch-up script knows we ran."""
+    try:
+        state = json.loads(STATE_FILE.read_text()) if STATE_FILE.exists() else {}
+    except Exception:
+        state = {}
+    state["cognitive-decay"] = datetime.now().isoformat()
+    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+
+def main():
+    ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    print(f"[{ts}] Cognitive decay starting...")
+
+    # 0. Process quarantine FIRST — promote/reject/expire pending items
+    #    BUG FIX 26-Mar-2026: quarantine was NEVER processed automatically.
+    #    78 items were stuck as pending indefinitely.
+    try:
+        q_result = cognitive.process_quarantine()
+        print(f"[{ts}] Quarantine: {q_result['promoted']} promoted, {q_result['rejected']} rejected, "
+              f"{q_result['expired']} expired, {q_result['still_pending']} still pending.")
+    except Exception as e:
+        print(f"[{ts}] Quarantine processing error: {e}")
+
+    # 0b. Purge test/dev memories from STM
+    try:
+        test_purged = cognitive.gc_test_memories()
+        if test_purged > 0:
+            print(f"[{ts}] Purged {test_purged} test/dev memories from STM.")
+    except Exception as e:
+        print(f"[{ts}] Test memory purge error: {e}")
+
+    # 1. Apply decay
+    cognitive.apply_decay()
+    print(f"[{ts}] Decay applied.")
+
+    # 2. Promote eligible STM → LTM
+    promoted = cognitive.promote_stm_to_ltm()
+    print(f"[{ts}] Promoted {promoted} STM memories to LTM.")
+
+    # 3. Garbage collect expired STM + sensory
+    gc_count = cognitive.gc_stm()
+    try:
+        gc_sensory = cognitive.gc_sensory(max_age_hours=48)
+        print(f"[{ts}] GC: removed {gc_count} expired STM, {gc_sensory} expired sensory.")
+    except Exception as e:
+        print(f"[{ts}] GC: removed {gc_count} expired STM. Sensory GC error: {e}")
+
+    # 4. Semantic consolidation — merge near-duplicate LTM (cosine > 0.9)
+    #    With discriminative fusion: siblings (different environments) are linked, not merged
+    try:
+        result = cognitive.consolidate_semantic(threshold=0.9, dry_run=False)
+        merged = result.get("merged", [])
+        siblings = result.get("siblings", [])
+        if merged:
+            print(f"[{ts}] Consolidated {len(merged)} duplicate LTM pairs:")
+            for m in merged[:10]:
+                print(f"[{ts}]   [{m['score']}] kept #{m['keep_id']} ({m['keep_access']} accesses), merged #{m['drop_id']}")
+        if siblings:
+            print(f"[{ts}] Linked {len(siblings)} sibling pairs (similar-but-incompatible):")
+            for s in siblings[:10]:
+                print(f"[{ts}]   [{s['score']}] #{s['memory_a_id']} <> #{s['memory_b_id']} differ in: {', '.join(s['discriminators'])}")
+        if not merged and not siblings:
+            print(f"[{ts}] No semantic duplicates or siblings found (threshold=0.9)")
+    except Exception as e:
+        print(f"[{ts}] Consolidation error: {e}")
+
+    # 5. Correction fatigue — mark memories corrected 3+ times as unreliable
+    # Closes Fase 3 item 4 of NEXO-AUDIT-2026-04-11. check_correction_fatigue
+    # already auto-decays strength to 0.2 and tags the memory as
+    # 'under_review', but the under_review tag is never read elsewhere in the
+    # codebase. The user could lose hours debugging a wrong memory before
+    # noticing it had been silently decayed. Surface as a daily followup so
+    # the operator sees fatigued memories at the next morning briefing.
+    try:
+        fatigued = cognitive.check_correction_fatigue()
+        if fatigued:
+            print(f"[{ts}] CORRECTION FATIGUE: {len(fatigued)} memories corrected 3+ times in 7d:")
+            for f in fatigued:
+                print(f"[{ts}]   LTM #{f['memory_id']} ({f['corrections_7d']}x): {f['content'][:80]}...")
+            try:
+                _open_correction_fatigue_followup(fatigued)
+            except Exception as fe:
+                print(f"[{ts}] Correction fatigue followup error: {fe}")
+        else:
+            print(f"[{ts}] No correction fatigue detected.")
+    except Exception as e:
+        print(f"[{ts}] Correction fatigue check error: {e}")
+
+    # 6. Memory Dreaming — discover hidden connections between recent memories
+    try:
+        dream_result = cognitive.dream_cycle(max_insights=15)
+        scanned = dream_result["memories_scanned"]
+        created = dream_result["insights_created"]
+        candidates = dream_result["candidates_found"]
+        print(f"[{ts}] Dream cycle: scanned {scanned} recent memories, {candidates} candidates, {created} insights created.")
+        for insight in dream_result["insights"][:10]:
+            print(f"[{ts}]   [{insight['similarity']}] {insight['title_a'][:40]} <-> {insight['title_b'][:40]}")
+    except Exception as e:
+        print(f"[{ts}] Dream cycle error: {e}")
+
+    # 7. Auto-merge duplicates (runs AFTER dream_cycle, higher threshold than consolidation)
+    try:
+        merge_result = cognitive.auto_merge_duplicates(threshold=0.92)
+        if merge_result["merged"] > 0:
+            print(f"[{ts}] Auto-merge: scanned {merge_result['scanned']}, merged {merge_result['merged']} duplicates, {merge_result['kept']} kept.")
+            for m in merge_result["merge_log"][:10]:
+                print(f"[{ts}]   [{m['similarity']}] kept #{m['kept_id']}, dropped #{m['dropped_id']}")
+        else:
+            print(f"[{ts}] Auto-merge: scanned {merge_result['scanned']}, no duplicates above 0.92 threshold.")
+    except Exception as e:
+        print(f"[{ts}] Auto-merge error: {e}")
+
+    # 9. Adaptive weight learning — Ridge regression from feedback-annotated entries
+    try:
+        sys.path.insert(0, str(NEXO_CODE / "plugins"))
+        from adaptive_mode import learn_weights, prune_adaptive_log, check_weight_rollback
+
+        rollback = check_weight_rollback()
+        if rollback["status"] == "rolled_back":
+            print(f"[{ts}] WEIGHT ROLLBACK: {rollback['reason']}")
+        elif rollback["status"] == "ok":
+            print(f"[{ts}] Weight health: pre={rollback['pre_rate']}/day, post={rollback['post_rate']}/day")
+        elif rollback["status"] != "no_learned_weights":
+            print(f"[{ts}] Weight rollback: {rollback['status']}")
+
+        result = learn_weights()
+        if result["status"] in ("shadow", "active"):
+            mode_label = "SHADOW" if result["status"] == "shadow" else "ACTIVE"
+            print(f"[{ts}] Learned weights ({mode_label}) from {result['samples']} samples. Max drift: {result['max_drift']:.4f}")
+            for signal, weight in result["weights"].items():
+                drift = result["drift"][signal]
+                arrow = "+" if drift > 0 else "" if drift < 0 else "="
+                print(f"[{ts}]   {signal}: {weight:.4f} ({arrow}{drift:.4f} from static)")
+        elif result["status"] == "insufficient_data":
+            print(f"[{ts}] Weight learning: {result['samples']}/{result['min_required']} samples (waiting)")
+        else:
+            print(f"[{ts}] Weight learning: {result['status']}")
+
+        pruned = prune_adaptive_log(max_age_days=90)
+        if pruned > 0:
+            print(f"[{ts}] Pruned {pruned} adaptive_log entries >90 days")
+    except Exception as e:
+        print(f"[{ts}] Adaptive weight learning error: {e}")
+
+    # 10. Project somatic events from nexo.db -> cognitive.db
+    try:
+        projected = cognitive.somatic_project_events()
+        if projected > 0:
+            print(f"[{ts}] Somatic projection: {projected} events projected to cognitive.db")
+    except Exception as e:
+        print(f"[{ts}] Somatic projection error: {e}")
+
+    # 11. Somatic marker nightly decay
+    try:
+        decayed = cognitive.somatic_nightly_decay(gamma=0.95)
+        print(f"[{ts}] Somatic decay: {decayed} markers processed (x0.95)")
+    except Exception as e:
+        print(f"[{ts}] Somatic decay error: {e}")
+
+    # 8. Stats
+    stats = cognitive.get_stats()
+    print(f"[{ts}] STM: {stats['stm_active']} active (+{stats.get('stm_promoted', 0)} promoted, {stats.get('stm_total', 0)} total) | LTM: {stats['ltm_active']} active, {stats['ltm_dormant']} dormant")
+    print(f"[{ts}] Done.")
+
+    update_catchup_state()
+
+
+if __name__ == "__main__":
+    main()

package/src/scripts/nexo-cortex-cycle 2.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""NEXO Cortex Cycle — continuous quality validation.
+
+Scheduled every 6 hours by src/crons/manifest.json (id: cortex-cycle).
+Closes Fase 2 item 6 of NEXO-AUDIT-2026-04-11.
+
+Until this script existed, Cortex evaluations only ran when an agent
+explicitly invoked nexo_cortex_decide / nexo_cortex_check during a task.
+There was no continuous loop watching for quality drops, so a degraded
+recommendation pattern could persist indefinitely between user reports.
+
+What this script does (idempotent and best-effort):
+
+1. Loads cortex_evaluation_summary for the last 7 days and last 1 day.
+2. Persists the snapshot to ~/.nexo/operations/cortex-quality-latest.json
+   so dashboards / morning briefings can read fresh metrics without
+   re-running the SQL.
+3. Detects degradation signals on the 7-day window. The criteria are
+   intentionally conservative to avoid false alarms on small samples:
+     a. recommendation_accept_rate < 50% AND total_evaluations >= 10
+     b. linked_outcome_success_rate < 50% AND linked_outcomes_resolved >= 5
+     c. override_success_rate > recommended_success_rate by >= 20pp
+        AND linked_outcomes_resolved >= 5
+4. Opens (or refreshes) NF-CORTEX-QUALITY-DROP followup with the offending
+   metrics when degradation is detected. Idempotent: if a non-PENDING /
+   resolved followup of the same id already exists, it is updated in
+   place rather than duplicated.
+5. Logs every run to ~/.nexo/logs/cortex-cycle.log.
+
+Catchup-friendly: a stale plist firing twice in quick succession is fine.
+The quality file is rewritten in place, the followup is upserted, no
+mutating side effects beyond those.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+_script_dir = Path(__file__).resolve().parent
+_repo_src = _script_dir.parent  # src/scripts/ -> src/
+NEXO_CODE = Path(
+    os.environ.get(
+        "NEXO_CODE",
+        str(_repo_src) if (_repo_src / "server.py").exists() else str(NEXO_HOME),
+    )
+)
+sys.path.insert(0, str(NEXO_CODE))
+
+OPERATIONS_DIR = NEXO_HOME / "operations"
+LOGS_DIR = NEXO_HOME / "logs"
+QUALITY_FILE = OPERATIONS_DIR / "cortex-quality-latest.json"
+LOG_FILE = LOGS_DIR / "cortex-cycle.log"
+FOLLOWUP_ID = "NF-CORTEX-QUALITY-DROP"
+
+ACCEPT_RATE_FLOOR = 50.0
+ACCEPT_RATE_MIN_SAMPLE = 10
+LINKED_SUCCESS_FLOOR = 50.0
+LINKED_MIN_SAMPLE = 5
+OVERRIDE_GAP_THRESHOLD = 20.0  # percentage points
+
+
+def _log(msg: str) -> None:
+    """Append a timestamped line to LOG_FILE. Best-effort, never raises."""
+    try:
+        LOGS_DIR.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now().isoformat(timespec="seconds")
+        with LOG_FILE.open("a", encoding="utf-8") as fh:
+            fh.write(f"[{ts}] {msg}\n")
+    except Exception:
+        pass
+    print(msg)
+
+
+def detect_quality_signals(summary: dict) -> list[dict]:
+    """Inspect a cortex_evaluation_summary dict and return degradation signals.
+
+    Each signal is a dict with at least:
+        - kind: short identifier (accept_rate / linked_success / override_gap)
+        - severity: warn | error
+        - message: human-readable explanation
+        - metric_value: the failing measurement
+        - threshold: the floor it dropped below
+
+    Returns an empty list when nothing is degraded. Pure function so it can
+    be unit-tested without touching the DB.
+    """
+    signals: list[dict] = []
+    if not isinstance(summary, dict):
+        return signals
+
+    total = int(summary.get("total_evaluations") or 0)
+    accept_rate = float(summary.get("recommendation_accept_rate") or 0.0)
+    linked_total = int(summary.get("linked_outcomes_total") or 0)
+    linked_met = int(summary.get("linked_outcomes_met") or 0)
+    linked_missed = int(summary.get("linked_outcomes_missed") or 0)
+    linked_pending = int(summary.get("linked_outcomes_pending") or 0)
+    linked_resolved = linked_met + linked_missed
+    if linked_resolved <= 0 and linked_total > 0:
+        # Older callers may omit the met/missed counters; fall back to total minus pending.
+        linked_resolved = max(0, linked_total - linked_pending)
+    linked_success = float(summary.get("linked_outcome_success_rate") or 0.0)
+    recommended_success = float(summary.get("recommended_success_rate") or 0.0)
+    override_success = float(summary.get("override_success_rate") or 0.0)
+
+    if total >= ACCEPT_RATE_MIN_SAMPLE and accept_rate < ACCEPT_RATE_FLOOR:
+        signals.append({
+            "kind": "accept_rate",
+            "severity": "warn",
+            "metric_value": accept_rate,
+            "threshold": ACCEPT_RATE_FLOOR,
+            "sample_size": total,
+            "message": (
+                f"Cortex recommendation accept rate {accept_rate:.1f}% on {total} "
+                f"evaluations is below the {ACCEPT_RATE_FLOOR:.0f}% floor. Users "
+                "are overriding the recommended choice more often than not."
+            ),
+        })
+
+    linked_scope = f"{linked_resolved} resolved linked outcomes"
+    if linked_pending > 0:
+        linked_scope += f" ({linked_total} total, {linked_pending} pending)"
+
+    if linked_resolved >= LINKED_MIN_SAMPLE and linked_success < LINKED_SUCCESS_FLOOR:
+        signals.append({
+            "kind": "linked_success",
+            "severity": "warn",
+            "metric_value": linked_success,
+            "threshold": LINKED_SUCCESS_FLOOR,
+            "sample_size": linked_resolved,
+            "message": (
+                f"Cortex linked-outcome success rate {linked_success:.1f}% on "
+                f"{linked_scope} is below the "
+                f"{LINKED_SUCCESS_FLOOR:.0f}% floor."
+            ),
+        })
+
+    if linked_resolved >= LINKED_MIN_SAMPLE:
+        gap = override_success - recommended_success
+        if gap >= OVERRIDE_GAP_THRESHOLD:
+            signals.append({
+                "kind": "override_gap",
+                "severity": "error",
+                "metric_value": gap,
+                "threshold": OVERRIDE_GAP_THRESHOLD,
+                "sample_size": linked_resolved,
+                "message": (
+                    f"Cortex overrides outperform recommendations by {gap:.1f}pp "
+                    f"(override {override_success:.1f}% vs recommended "
+                    f"{recommended_success:.1f}% on {linked_scope}). The "
+                    "recommender is mis-ranking choices."
+                ),
+            })
+
+    return signals
+
+
+def _persist_quality_snapshot(window_7d: dict, window_1d: dict, signals: list[dict]) -> None:
+    payload = {
+        "captured_at": datetime.now().isoformat(timespec="seconds"),
+        "window_7d": window_7d,
+        "window_1d": window_1d,
+        "signals": signals,
+        "schema": 1,
+    }
+    try:
+        OPERATIONS_DIR.mkdir(parents=True, exist_ok=True)
+        QUALITY_FILE.write_text(json.dumps(payload, ensure_ascii=False, indent=2))
+    except Exception as e:
+        _log(f"WARN: failed to persist quality snapshot: {e}")
+
+
+def _upsert_quality_followup(signals: list[dict]) -> str:
+    """Open or refresh NF-CORTEX-QUALITY-DROP. Returns the action taken.
+
+    Idempotent: if the followup already exists in PENDING status it is
+    updated in place rather than duplicated. If it exists but was already
+    resolved, a fresh row is inserted with the same id (REPLACE) so the
+    new degradation pattern is visible.
+    """
+    try:
+        from db import complete_followup, get_followup, get_db
+    except Exception as e:
+        _log(f"WARN: cannot import db helpers: {e}")
+        return "skipped_no_db"
+
+    try:
+        existing = get_followup(FOLLOWUP_ID)
+    except Exception as e:
+        _log(f"WARN: get_followup raised: {e}")
+        existing = None
+
+    if not signals:
+        if not existing:
+            return "no_signal"
+        status = str(existing.get("status") or "").upper()
+        if status.startswith("COMPLETED") or status in {"DELETED", "ARCHIVED", "BLOCKED", "WAITING", "CANCELLED"}:
+            return "no_signal"
+        try:
+            complete_followup(
+                FOLLOWUP_ID,
+                result=(
+                    "Auto-resolved by cortex-cycle: no active degradation signals in the "
+                    "current 7d window."
+                ),
+            )
+        except Exception as e:
+            _log(f"WARN: failed to close followup: {e}")
+            return "failed_close"
+        return "closed"
+
+    summary_lines = ["Cortex continuous validation found quality degradation:"]
+    for sig in signals:
+        summary_lines.append(
+            f"- [{sig['severity'].upper()}] {sig['kind']}: {sig['message']}"
+        )
+    summary_lines.append("")
+    summary_lines.append(
+        "Investigate cortex_evaluations recent rows, review goal profiles, "
+        "and consider tightening or relaxing the recommender heuristics."
+    )
+    description = "\n".join(summary_lines)
+    verification = (
+        "SELECT id, goal, recommended_choice, selected_choice, selection_source, "
+        "created_at FROM cortex_evaluations ORDER BY id DESC LIMIT 20"
+    )
+    now_epoch = datetime.now().timestamp()
+
+    try:
+        conn = get_db()
+        conn.execute(
+            "INSERT OR REPLACE INTO followups (id, description, date, status, "
+            "verification, created_at, updated_at, priority) "
+            "VALUES (?, ?, NULL, 'PENDING', ?, ?, ?, 'high')",
+            (FOLLOWUP_ID, description, verification, now_epoch, now_epoch),
+        )
+        try:
+            conn.commit()
+        except Exception:
+            pass
+    except Exception as e:
+        _log(f"WARN: failed to upsert followup: {e}")
+        return "failed"
+
+    return "refreshed" if existing else "opened"
+
+
+def run() -> int:
+    """Main cron entry point. Returns 0 on success, 2 on partial failure."""
+    try:
+        from db import cortex_evaluation_summary
+    except Exception as e:
+        _log(f"FATAL: cannot import cortex_evaluation_summary: {e}")
+        return 2
+
+    try:
+        window_7d = cortex_evaluation_summary(days=7)
+    except Exception as e:
+        _log(f"FATAL: cortex_evaluation_summary(7d) raised: {e}")
+        return 2
+
+    try:
+        window_1d = cortex_evaluation_summary(days=1)
+    except Exception as e:
+        _log(f"WARN: cortex_evaluation_summary(1d) raised: {e}")
+        window_1d = {"days": 1, "total_evaluations": 0, "error": str(e)}
+
+    signals = detect_quality_signals(window_7d)
+    _persist_quality_snapshot(window_7d, window_1d, signals)
+
+    total = int(window_7d.get("total_evaluations") or 0)
+    accept_rate = float(window_7d.get("recommendation_accept_rate") or 0.0)
+    if total == 0:
+        _log("Cortex cycle: no evaluations in 7d window — nothing to validate")
+    else:
+        _log(
+            f"Cortex cycle: {total} evaluations in 7d, accept_rate={accept_rate:.1f}%, "
+            f"signals={len(signals)}"
+        )
+
+    action = _upsert_quality_followup(signals)
+    if signals or action not in {"no_signal"}:
+        _log(f"Cortex cycle: followup {FOLLOWUP_ID} {action} ({len(signals)} signal(s))")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run())

package/src/scripts/nexo-cron-wrapper 2.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# NEXO Cron Wrapper — Records execution in cron_runs table.
+# Usage: nexo-cron-wrapper.sh <cron_id> <command...>
+# Example: nexo-cron-wrapper.sh deep-sleep bash nexo-deep-sleep.sh
+#
+# Wraps any cron command to automatically record start/end/exit_code/summary.
+# Used by sync.py when generating LaunchAgents from manifest.json.
+
+set -uo pipefail
+
+CRON_ID="${1:?Usage: nexo-cron-wrapper.sh <cron_id> <command...>}"
+shift
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+DB="$NEXO_HOME/data/nexo.db"
+
+# Record start
+RUN_ID=$(sqlite3 "$DB" "INSERT INTO cron_runs (cron_id) VALUES ('$CRON_ID'); SELECT last_insert_rowid();" 2>/dev/null)
+
+if [ -z "$RUN_ID" ]; then
+    # DB not ready — run without tracking
+    exec "$@"
+fi
+
+# Run the actual command, capture output
+OUTPUT_FILE=$(mktemp)
+"$@" > "$OUTPUT_FILE" 2>&1
+EXIT_CODE=$?
+
+# Extract summary (last meaningful line, max 500 chars)
+SUMMARY=$(tail -5 "$OUTPUT_FILE" | grep -v "^$" | tail -1 | head -c 500 | sed "s/'/''/g")
+
+# Extract error if failed
+ERROR=""
+if [ $EXIT_CODE -ne 0 ]; then
+    ERROR=$(grep -i "error\|exception\|fail\|traceback" "$OUTPUT_FILE" | tail -1 | head -c 500 | sed "s/'/''/g")
+fi
+
+# Record end
+sqlite3 "$DB" "
+    UPDATE cron_runs SET
+        ended_at = datetime('now'),
+        exit_code = $EXIT_CODE,
+        summary = '$SUMMARY',
+        error = '$ERROR',
+        duration_secs = ROUND((julianday(datetime('now')) - julianday(started_at)) * 86400, 1)
+    WHERE id = $RUN_ID;
+" 2>/dev/null
+
+# Clean output
+rm -f "$OUTPUT_FILE"
+
+exit $EXIT_CODE