nexo-brain 2.5.1 → 2.6.0

package/src/doctor/providers/runtime.py

@@ -11,17 +11,26 @@ import sys
 import time
 from pathlib import Path
 
+from cron_recovery import should_run_at_load
 from doctor.models import DoctorCheck
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parents[2])))
 LAUNCH_AGENTS_DIR = Path.home() / "Library" / "LaunchAgents"
+PROTECTED_MACOS_ROOTS = (
+    Path.home() / "Documents",
+    Path.home() / "Desktop",
+    Path.home() / "Downloads",
+    Path.home() / "Library" / "Mobile Documents",
+)
 
 # Freshness thresholds in seconds
 IMMUNE_FRESHNESS = 3600  # 1 hour (runs every 30 min)
 WATCHDOG_FRESHNESS = 3600  # 1 hour (runs every 30 min)
 DEFAULT_CRON_THRESHOLD = 7200  # Fallback when manifest data is unavailable
 SPECIAL_LAUNCHAGENT_IDS = {"prevent-sleep", "tcc-approve"}
+SPECIAL_ENV_NORMALIZE_IDS = SPECIAL_LAUNCHAGENT_IDS
+OPTIONALS_FILE = NEXO_HOME / "config" / "optionals.json"
 
 
 def _file_age_seconds(path: Path) -> float | None:
@@ -64,11 +73,23 @@ def _parse_timestamp(value: str) -> dt.datetime | None:
         return None
 
 
-def _cron_expectations() -> dict[str, dict]:
+def _enabled_optionals() -> dict[str, bool]:
+    try:
+        if OPTIONALS_FILE.is_file():
+            data = json.loads(OPTIONALS_FILE.read_text())
+            if isinstance(data, dict):
+                return {str(k): bool(v) for k, v in data.items()}
+    except Exception:
+        pass
+    return {}
+
+
+def _enabled_manifest_crons() -> list[dict]:
     manifest_candidates = [
         NEXO_HOME / "crons" / "manifest.json",
         NEXO_CODE / "crons" / "manifest.json",
     ]
+    optionals = _enabled_optionals()
     for manifest_path in manifest_candidates:
         if not manifest_path.is_file():
             continue
@@ -77,87 +98,104 @@ def _cron_expectations() -> dict[str, dict]:
         except Exception:
             continue
 
-        expectations = {}
+        enabled = []
         for cron in data.get("crons", []):
             cron_id = cron.get("id")
-            if not cron_id or cron.get("run_at_load"):
+            if not cron_id:
+                continue
+            optional_key = cron.get("optional")
+            if optional_key and not optionals.get(optional_key, False):
                 continue
+            enabled.append(cron)
+        return enabled
+    return []
 
-            interval_seconds = cron.get("interval_seconds")
-            schedule = cron.get("schedule") or {}
-            if interval_seconds:
-                threshold = max(int(interval_seconds) * 3, int(interval_seconds) + 600)
-                label = f"every {int(interval_seconds) // 60}m"
-            elif "weekday" in schedule:
-                threshold = 8 * 86400
-                label = "weekly"
-            elif "hour" in schedule and "minute" in schedule:
-                threshold = 36 * 3600
-                label = "daily"
-            else:
-                threshold = DEFAULT_CRON_THRESHOLD
-                label = "custom"
 
-            expectations[cron_id] = {"threshold": threshold, "label": label}
-        return expectations
-    return {}
+def _cron_expectations() -> dict[str, dict]:
+    expectations = {}
+    for cron in _enabled_manifest_crons():
+        cron_id = cron.get("id")
+        if not cron_id or cron.get("keep_alive"):
+            continue
+        if cron.get("run_at_load") and not cron.get("interval_seconds") and not cron.get("schedule"):
+            continue
 
+        interval_seconds = cron.get("interval_seconds")
+        schedule = cron.get("schedule") or {}
+        if interval_seconds:
+            threshold = max(int(interval_seconds) * 3, int(interval_seconds) + 600)
+            label = f"every {int(interval_seconds) // 60}m"
+        elif "weekday" in schedule:
+            threshold = 8 * 86400
+            label = "weekly"
+        elif "hour" in schedule and "minute" in schedule:
+            threshold = 36 * 3600
+            label = "daily"
+        else:
+            threshold = DEFAULT_CRON_THRESHOLD
+            label = "custom"
 
-def _run_at_load_cron_ids() -> set[str]:
-    return {
-        cron_id
-        for cron_id, expected in _launchagent_schedule_expectations().items()
-        if expected.get("RunAtLoad") is True
-    }
+        expectations[cron_id] = {"threshold": threshold, "label": label}
+    return expectations
 
 
-def _launchagent_schedule_expectations() -> dict[str, dict]:
-    manifest_candidates = [
-        NEXO_HOME / "crons" / "manifest.json",
-        NEXO_CODE / "crons" / "manifest.json",
-    ]
-    for manifest_path in manifest_candidates:
-        if not manifest_path.is_file():
+def _run_at_load_cron_ids() -> set[str]:
+    ids: set[str] = set()
+    for cron_id, expected in _launchagent_schedule_expectations().items():
+        if expected.get("RunAtLoad") is not True:
             continue
-        try:
-            data = _load_json(manifest_path)
-        except Exception:
+        if expected.get("StartInterval") or expected.get("StartCalendarInterval") or expected.get("KeepAlive"):
             continue
+        ids.add(cron_id)
+    return ids
 
-        expectations = {}
-        for cron in data.get("crons", []):
-            cron_id = cron.get("id")
-            if not cron_id:
-                continue
 
-            expected = {
-                "StartInterval": None,
-                "StartCalendarInterval": None,
-                "RunAtLoad": None,
-            }
-            if cron.get("run_at_load"):
-                expected["RunAtLoad"] = True
-            elif "interval_seconds" in cron:
-                expected["StartInterval"] = int(cron["interval_seconds"])
-            elif "schedule" in cron:
-                schedule = cron.get("schedule") or {}
-                cal = {}
-                if "hour" in schedule:
-                    cal["Hour"] = schedule["hour"]
-                if "minute" in schedule:
-                    cal["Minute"] = schedule["minute"]
-                if "weekday" in schedule:
-                    cal["Weekday"] = schedule["weekday"]
-                expected["StartCalendarInterval"] = cal
-            expectations[cron_id] = expected
-        return expectations
-    return {}
+def _launchagent_schedule_expectations() -> dict[str, dict]:
+    expectations = {}
+    for cron in _enabled_manifest_crons():
+        cron_id = cron.get("id")
+        if not cron_id:
+            continue
+
+        expected = {
+            "StartInterval": None,
+            "StartCalendarInterval": None,
+            "RunAtLoad": None,
+            "KeepAlive": None,
+            "schedule_configured": False,
+        }
+        if cron.get("keep_alive"):
+            expected["RunAtLoad"] = True
+            expected["KeepAlive"] = True
+            expected["schedule_configured"] = True
+        elif "interval_seconds" in cron:
+            expected["StartInterval"] = int(cron["interval_seconds"])
+            expected["RunAtLoad"] = True if should_run_at_load(cron) else None
+            expected["schedule_configured"] = True
+        elif "schedule" in cron:
+            schedule = cron.get("schedule") or {}
+            cal = {}
+            if "hour" in schedule:
+                cal["Hour"] = schedule["hour"]
+            if "minute" in schedule:
+                cal["Minute"] = schedule["minute"]
+            if "weekday" in schedule:
+                cal["Weekday"] = schedule["weekday"]
+            expected["StartCalendarInterval"] = cal
+            expected["RunAtLoad"] = True if should_run_at_load(cron) else None
+            expected["schedule_configured"] = True
+        elif should_run_at_load(cron):
+            expected["RunAtLoad"] = True
+            expected["schedule_configured"] = True
+        expectations[cron_id] = expected
+    return expectations
 
 
 def _managed_launchagent_plists() -> list[tuple[str, Path]]:
     ids = set(SPECIAL_LAUNCHAGENT_IDS)
-    for cron_id in _launchagent_schedule_expectations().keys():
-        ids.add(cron_id)
+    for cron_id, expected in _launchagent_schedule_expectations().items():
+        if expected.get("schedule_configured"):
+            ids.add(cron_id)
 
     plists = []
     for cron_id in sorted(ids):
@@ -175,6 +213,43 @@ def _extract_launchctl_value(output: str, prefix: str) -> str | None:
     return None
 
 
+def _is_protected_macos_path(value: str | os.PathLike[str] | None) -> bool:
+    if not value or platform.system() != "Darwin":
+        return False
+    try:
+        raw = str(value).replace("~", str(Path.home()), 1)
+        candidate = Path(raw).expanduser().resolve(strict=False)
+    except Exception:
+        return False
+    return any(candidate == root or root in candidate.parents for root in PROTECTED_MACOS_ROOTS)
+
+
+def _plist_runtime_paths(plist_data: dict) -> list[str]:
+    paths: list[str] = []
+    env = plist_data.get("EnvironmentVariables") or {}
+    for key in ("NEXO_HOME", "NEXO_CODE"):
+        value = env.get(key)
+        if value:
+            paths.append(str(value))
+    for arg in plist_data.get("ProgramArguments") or []:
+        arg_str = str(arg)
+        if arg_str.startswith("/") or arg_str.startswith("~"):
+            paths.append(arg_str)
+    return paths
+
+
+def _recent_permission_denial(cron_id: str, max_age_seconds: int = 7 * 86400) -> bool:
+    stderr_path = NEXO_HOME / "logs" / f"{cron_id}-stderr.log"
+    age = _file_age_seconds(stderr_path)
+    if age is None or age > max_age_seconds:
+        return False
+    try:
+        tail = "\n".join(stderr_path.read_text(errors="ignore").splitlines()[-50:])
+    except Exception:
+        return False
+    return "Operation not permitted" in tail
+
+
 def _repair_launchagents(items: list[tuple[str, Path]]) -> tuple[bool, list[str]]:
     evidence = []
     uid = str(os.getuid())
@@ -199,6 +274,33 @@ def _repair_launchagents(items: list[tuple[str, Path]]) -> tuple[bool, list[str]
     return ok, evidence
 
 
+def _repair_special_launchagent_plists(items: list[tuple[str, Path]]) -> tuple[bool, list[str]]:
+    evidence: list[str] = []
+    ok = True
+    for cron_id, plist_path in items:
+        if cron_id not in SPECIAL_ENV_NORMALIZE_IDS:
+            continue
+        try:
+            with plist_path.open("rb") as fh:
+                plist_data = plistlib.load(fh)
+            env = plist_data.setdefault("EnvironmentVariables", {})
+            changed = False
+            if env.get("NEXO_CODE") != str(NEXO_HOME):
+                env["NEXO_CODE"] = str(NEXO_HOME)
+                changed = True
+            if env.get("NEXO_HOME") != str(NEXO_HOME):
+                env["NEXO_HOME"] = str(NEXO_HOME)
+                changed = True
+            if changed:
+                with plist_path.open("wb") as fh:
+                    plistlib.dump(plist_data, fh)
+                evidence.append(f"com.nexo.{cron_id}: normalized special LaunchAgent env")
+        except Exception as e:
+            ok = False
+            evidence.append(f"com.nexo.{cron_id}: {e}")
+    return ok, evidence
+
+
 def _sync_launchagents_from_manifest() -> tuple[bool, list[str]]:
     sync_path = NEXO_CODE / "crons" / "sync.py"
     if not sync_path.is_file():
@@ -456,15 +558,20 @@ def check_cron_freshness() -> DoctorCheck:
         stale = []
         expectations = _cron_expectations()
         ignored_crons = _run_at_load_cron_ids()
+        tracked_crons = set(expectations)
         now = time.time()
         for row in rows:
             cron_id = row[0]
             if cron_id in ignored_crons:
                 continue
+            if cron_id not in tracked_crons:
+                continue
             parsed = _parse_timestamp(row[1]) if row[1] else None
             if parsed is None:
                 stale.append(f"{cron_id}: unreadable timestamp {row[1]!r}")
                 continue
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=dt.timezone.utc)
 
             age = now - parsed.timestamp()
             expected = expectations.get(cron_id, {"threshold": DEFAULT_CRON_THRESHOLD, "label": "runtime default"})
@@ -485,7 +592,7 @@ def check_cron_freshness() -> DoctorCheck:
             tier="runtime",
             status="healthy",
             severity="info",
-            summary=f"All {len(rows)} tracked crons ran recently",
+            summary=f"All {len(tracked_crons)} tracked crons ran recently",
         )
     except Exception as e:
         return DoctorCheck(
@@ -522,6 +629,8 @@ def check_launchagent_integrity(fix: bool = False) -> DoctorCheck:
     problems = []
     problem_items: list[tuple[str, Path]] = []
     tmp_drift = False
+    tcc_risk = False
+    tcc_failure = False
     schedule_expectations = _launchagent_schedule_expectations()
     for cron_id, plist_path in managed:
         label = f"com.nexo.{cron_id}"
@@ -560,6 +669,18 @@ def check_launchagent_integrity(fix: bool = False) -> DoctorCheck:
             problems.append(f"{label}: plist unreadable ({e})")
             continue
 
+        protected_refs = [path for path in _plist_runtime_paths(plist_data) if _is_protected_macos_path(path)]
+        if protected_refs:
+            tcc_risk = True
+            if _recent_permission_denial(cron_id):
+                tcc_failure = True
+                problems.append(
+                    f"{label}: recent 'Operation not permitted' while using protected macOS path {protected_refs[0]}"
+                )
+            else:
+                problems.append(f"{label}: runtime points into protected macOS path {protected_refs[0]}")
+            had_problem = True
+
         for env_key in ("NEXO_HOME", "NEXO_CODE"):
             expected_value = env.get(env_key)
             if not expected_value:
@@ -572,16 +693,23 @@ def check_launchagent_integrity(fix: bool = False) -> DoctorCheck:
                     tmp_drift = True
 
         expected_schedule = schedule_expectations.get(cron_id)
-        if expected_schedule is not None:
+        if expected_schedule is not None and expected_schedule.get("schedule_configured"):
             actual_schedule = {
                 "StartInterval": plist_data.get("StartInterval"),
                 "StartCalendarInterval": plist_data.get("StartCalendarInterval"),
                 "RunAtLoad": plist_data.get("RunAtLoad"),
+                "KeepAlive": plist_data.get("KeepAlive"),
             }
-            if actual_schedule != expected_schedule:
+            target_schedule = {
+                "StartInterval": expected_schedule.get("StartInterval"),
+                "StartCalendarInterval": expected_schedule.get("StartCalendarInterval"),
+                "RunAtLoad": expected_schedule.get("RunAtLoad"),
+                "KeepAlive": expected_schedule.get("KeepAlive"),
+            }
+            if actual_schedule != target_schedule:
                 problems.append(
                     f"{label}: schedule drift "
-                    f"(actual={actual_schedule}, expected={expected_schedule})"
+                    f"(actual={actual_schedule}, expected={target_schedule})"
                 )
                 had_problem = True
 
@@ -600,28 +728,37 @@ def check_launchagent_integrity(fix: bool = False) -> DoctorCheck:
     check = DoctorCheck(
         id="runtime.launchagents",
         tier="runtime",
-        status="critical" if tmp_drift else "degraded",
-        severity="error" if tmp_drift else "warn",
-        summary=f"LaunchAgent drift detected in {len(problems)} job(s)",
+        status="critical" if (tmp_drift or tcc_failure) else "degraded",
+        severity="error" if (tmp_drift or tcc_failure) else "warn",
+        summary=(
+            f"LaunchAgent drift detected in {len(problems)} job(s)"
+            if not tcc_risk
+            else f"LaunchAgent drift or TCC/runtime path risk detected in {len(problems)} job(s)"
+        ),
         evidence=problems[:10],
         repair_plan=[
             "Reload the affected LaunchAgents from ~/Library/LaunchAgents",
             "Re-sync core cron plists from crons/manifest.json if the schedule drifted",
             "If any job is loaded from /tmp, boot it out before bootstrapping the real plist",
+            "If any core job points into Documents/Desktop/Downloads, re-sync it so it runs from NEXO_HOME instead",
         ],
-        escalation_prompt="Launchd is serving stale or drifted NEXO jobs. Compare loaded job paths with plist paths on disk.",
+        escalation_prompt=(
+            "Launchd is serving stale or drifted NEXO jobs. Compare loaded job paths with plist paths on disk, "
+            "and treat recent 'Operation not permitted' against Documents/Desktop/Downloads as a TCC/runtime path issue."
+        ),
     )
 
     if fix:
         sync_ok, sync_evidence = _sync_launchagents_from_manifest()
+        special_ok, special_evidence = _repair_special_launchagent_plists(problem_items)
         repaired, repair_evidence = _repair_launchagents(problem_items)
-        if sync_ok and repaired:
+        if sync_ok and special_ok and repaired:
             post_check = check_launchagent_integrity(fix=False)
             if post_check.status == "healthy":
                 post_check.fixed = True
                 post_check.summary += " (fixed)"
                 return post_check
-        check.evidence.extend((sync_evidence + repair_evidence)[:10])
+        check.evidence.extend((sync_evidence + special_evidence + repair_evidence)[:10])
     return check
 
 
@@ -674,6 +811,65 @@ def check_skill_health(fix: bool = False) -> DoctorCheck:
     )
 
 
+def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
+    """Check the DB-backed personal script registry against filesystem/plists."""
+    try:
+        from db import init_db, get_personal_script_health_report
+        from script_registry import sync_personal_scripts
+
+        init_db()
+        sync_personal_scripts(prune_missing=True)
+        report = get_personal_script_health_report(fix=fix)
+    except Exception as e:
+        return DoctorCheck(
+            id="runtime.personal_scripts",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary=f"Personal scripts registry check failed: {e}",
+        )
+
+    issues = report.get("issues", [])
+    if not issues:
+        audit = report.get("schedule_audit", {}).get("summary", {})
+        summary = (
+            f"Personal scripts registered "
+            f"({report.get('scripts', 0)} scripts, {report.get('schedules', 0)} schedules"
+            f", {audit.get('healthy', report.get('schedules', 0))} managed)"
+        )
+        if fix:
+            summary += " (fixed)"
+        return DoctorCheck(
+            id="runtime.personal_scripts",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary=summary,
+            fixed=fix,
+        )
+
+    errors = [issue for issue in issues if issue.get("severity") == "error"]
+    warnings = [issue for issue in issues if issue.get("severity") != "error"]
+    return DoctorCheck(
+        id="runtime.personal_scripts",
+        tier="runtime",
+        status="critical" if errors else "degraded",
+        severity="error" if errors else "warn",
+        summary=f"Personal scripts registry issues detected in {len(issues)} item(s)",
+        evidence=[issue["message"] for issue in issues[:10]],
+        repair_plan=[
+            "Run nexo scripts sync to reconcile filesystem scripts and personal LaunchAgents",
+            "Run nexo scripts reconcile so declared schedules are recreated through the official flow",
+            "Use nexo doctor --tier runtime --fix to apply the safe reconcile path for declared schedules",
+            "Keep personal scripts in NEXO_HOME/scripts so updates do not collide with core",
+        ],
+        escalation_prompt=(
+            "Personal script metadata, files, and personal cron schedules are out of sync. "
+            "Reconcile NEXO_HOME/scripts with personal LaunchAgents without treating them as core crons."
+        ),
+    )
+
+
 def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all runtime-tier checks. Read-only by default."""
     return [
@@ -682,5 +878,6 @@ def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
         check_stale_sessions(),
         check_cron_freshness(),
         check_launchagent_integrity(fix=fix),
+        check_personal_script_registry(fix=fix),
         check_skill_health(fix=fix),
     ]

package/src/evolution_cycle.py

@@ -271,12 +271,15 @@ def build_evolution_prompt(week_data: dict, objective: dict) -> str:
     if mode == "review":
         mode_desc = "review-only, nothing executes automatically"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/, ~/.nexo/brain/"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md"
     elif mode == "managed":
         mode_desc = f"owner-managed, max {max_auto} auto-applied changes with rollback and followups"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/, ~/.nexo/brain/, NEXO_CODE/src, repo bin/docs/templates/tests"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, personality.md, user-profile.md"
     else:
         mode_desc = f"public auto, max {max_auto} auto-applied changes in personal safe zones"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md"
 
     prompt = f"""You are NEXO Evolution — the weekly self-improvement cycle.
 
@@ -311,7 +314,7 @@ LOOK FOR:
 
 SAFETY:
 - Safe zones for this mode: {safe_zones}
-- IMMUTABLE files (never touch): db.py, server.py, plugin_loader.py, cognitive.py, CLAUDE.md
+- IMMUTABLE files (never touch in this mode): {immutable_files}
 - Every change needs: what file, what to change, why, risk, how to verify
 - AUTO changes must be deterministic. If the edit is ambiguous, risky, or needs human taste, mark it as "propose".
 - In managed mode, failed AUTO changes will be rolled back automatically and turned into followups with evidence.

package/src/plugins/personal_scripts.py

@@ -0,0 +1,117 @@
+"""NEXO Personal Scripts — registry-backed management for user scripts."""
+
+import json
+
+from db import init_db, list_personal_scripts, list_personal_script_schedules
+from plugins.schedule import handle_schedule_add
+from script_registry import (
+    classify_scripts_dir,
+    create_script,
+    ensure_personal_schedules,
+    reconcile_personal_scripts,
+    remove_personal_script,
+    sync_personal_scripts,
+    unschedule_personal_script,
+)
+
+
+def handle_personal_scripts_sync() -> str:
+    init_db()
+    result = sync_personal_scripts()
+    return json.dumps(result, ensure_ascii=False)
+
+
+def handle_personal_scripts_classify() -> str:
+    return json.dumps(classify_scripts_dir(), ensure_ascii=False)
+
+
+def handle_personal_scripts_list(include_schedules: bool = True) -> str:
+    init_db()
+    sync_personal_scripts()
+    scripts = list_personal_scripts()
+    if include_schedules:
+        return json.dumps({"scripts": scripts}, ensure_ascii=False)
+
+    simplified = []
+    for script in scripts:
+        simplified.append({
+            "id": script["id"],
+            "name": script["name"],
+            "description": script.get("description", ""),
+            "runtime": script.get("runtime", "unknown"),
+            "path": script["path"],
+            "has_schedule": script.get("has_schedule", False),
+        })
+    return json.dumps({"scripts": simplified}, ensure_ascii=False)
+
+
+def handle_personal_script_create(
+    name: str,
+    description: str = "",
+    runtime: str = "python",
+    schedule: str = "",
+    interval_seconds: int = 0,
+) -> str:
+    init_db()
+    created = create_script(name, description=description, runtime=runtime)
+    if schedule or interval_seconds:
+        cron_id = created["name"]
+        handle_schedule_add(
+            cron_id=cron_id,
+            script=created["path"],
+            schedule=schedule,
+            interval_seconds=interval_seconds,
+            description=description,
+            script_type=runtime,
+        )
+        sync_result = sync_personal_scripts()
+        created["sync"] = sync_result
+    return json.dumps(created, ensure_ascii=False)
+
+
+def handle_personal_script_schedules() -> str:
+    init_db()
+    sync_personal_scripts()
+    return json.dumps({"schedules": list_personal_script_schedules()}, ensure_ascii=False)
+
+
+def handle_personal_scripts_reconcile(dry_run: bool = False) -> str:
+    init_db()
+    return json.dumps(reconcile_personal_scripts(dry_run=dry_run), ensure_ascii=False)
+
+
+def handle_personal_scripts_ensure_schedules(dry_run: bool = False) -> str:
+    init_db()
+    return json.dumps(ensure_personal_schedules(dry_run=dry_run), ensure_ascii=False)
+
+
+def handle_personal_script_unschedule(name: str) -> str:
+    init_db()
+    return json.dumps(unschedule_personal_script(name), ensure_ascii=False)
+
+
+def handle_personal_script_remove(name: str, keep_file: bool = False) -> str:
+    init_db()
+    return json.dumps(remove_personal_script(name, keep_file=keep_file), ensure_ascii=False)
+
+
+TOOLS = [
+    (handle_personal_scripts_sync, "nexo_personal_scripts_sync",
+     "Sync personal scripts and personal cron schedules from filesystem and LaunchAgents into the registry."),
+    (handle_personal_scripts_classify, "nexo_personal_scripts_classify",
+     "Classify files in NEXO_HOME/scripts into personal, core, ignored, and non-script buckets."),
+    (handle_personal_scripts_list, "nexo_personal_scripts_list",
+     "List personal scripts known to NEXO, optionally including attached schedules."),
+    (handle_personal_script_create, "nexo_personal_script_create",
+     "Create a new personal script in NEXO_HOME/scripts, register it, and optionally attach a schedule."),
+    (handle_personal_script_schedules, "nexo_personal_script_schedules",
+     "List registered personal script schedules."),
+    (handle_personal_scripts_reconcile, "nexo_personal_scripts_reconcile",
+     "Classify, sync, and ensure declared personal schedules so NEXO_HOME/scripts and personal crons stay aligned."),
+    (handle_personal_scripts_ensure_schedules, "nexo_personal_scripts_ensure_schedules",
+     "Create or repair personal script schedules declared in inline metadata."),
+    (handle_personal_script_unschedule, "nexo_personal_script_unschedule",
+     "Remove all personal schedules attached to a script without touching core crons."),
+    (handle_personal_script_remove, "nexo_personal_script_remove",
+     "Remove a personal script from the registry and optionally delete its file after unscheduling it."),
+]