nexo-brain 7.12.15 → 7.13.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.12.15",
+  "version": "7.13.3",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.12.15` is the current packaged-runtime line. Patch release — same-version packaged updates now still run the safe maintenance path, Deep Sleep clears process locks on shutdown, sent replies are recorded in durable continuity, and personal script schedule-marker drift is surfaced during reconcile. Result: coordinated Desktop bundles can refresh Brain safely without breaking install/update parity on macOS, Windows via WSL, or Linux.
+Version `7.13.3` is the current packaged-runtime line. Unified release — doctor now repairs orphan personal script metadata and ignores historical `versions/**` snapshots, `nexo update` prunes runtime snapshots older than two back, protocol compliance self-heals missing task-open/change-log/stale-session gaps, headless automation uses bounded timeouts, Guardian false positives are tightened, and Codex CLI parity is release-gated. Result: coordinated Desktop bundles can ship the new Brain without changing the Mac/Windows installation contract.
+
+Previously in `7.12.15`: patch release — same-version packaged updates now still run the safe maintenance path, Deep Sleep clears process locks on shutdown, sent replies are recorded in durable continuity, and personal script schedule-marker drift is surfaced during reconcile. Result: coordinated Desktop bundles can refresh Brain safely without breaking install/update parity on macOS, Windows via WSL, or Linux.
 
 Previously in `7.12.0`: minor release — adds `nexo support-snapshot` for generic local runtime diagnostics and completes the silent-reminder hardening on the live Protocol Enforcer path. The support collector emits one JSON bundle with version/platform metadata, runtime path presence, health-check output, and recent event/operation tails, while map-driven reminders (`nexo_startup`, `nexo_smart_startup`, `nexo_heartbeat`, `nexo_reminders`, `nexo_session_diary_*`, `nexo_stop`, `nexo_task_close`, compaction checkpoint prompts) now say explicitly that silence owns the entire reminder turn.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.12.15",
+  "version": "7.13.3",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/auto_close_sessions.py

@@ -152,6 +152,36 @@ def promote_draft_to_diary(sid: str, draft: dict, task: str = ""):
     delete_diary_draft(sid)
 
 
+def auto_close_open_protocol_tasks(conn, sid: str, task: str = "") -> list[str]:
+    """Close stale open protocol tasks as partial when their session is reaped."""
+    rows = conn.execute(
+        """SELECT task_id, goal
+           FROM protocol_tasks
+           WHERE session_id = ? AND status = 'open'
+           ORDER BY opened_at ASC""",
+        (sid,),
+    ).fetchall()
+    closed: list[str] = []
+    for row in rows:
+        task_id = row["task_id"]
+        goal = str(row["goal"] or "")
+        evidence = (
+            f"Auto-closed as partial because session {sid} became stale before an explicit nexo_task_close. "
+            f"Session task: {task or 'unknown'}. Open goal: {goal[:240]}"
+        )
+        conn.execute(
+            """UPDATE protocol_tasks
+               SET status = 'partial',
+                   close_evidence = ?,
+                   outcome_notes = 'auto-close: stale session ended without explicit task_close',
+                   closed_at = datetime('now')
+               WHERE task_id = ? AND status = 'open'""",
+            (evidence[:4000], task_id),
+        )
+        closed.append(task_id)
+    return closed
+
+
 def main():
     init_db()
     conn = get_db()
@@ -161,9 +191,12 @@ def main():
         print(f"[{datetime.datetime.now().isoformat(timespec='seconds')}] No stale sessions")
         return
 
+    closed_task_ids: list[str] = []
     for session in orphans:
         sid = session["sid"]
         draft = get_diary_draft(sid)
+        closed_tasks = auto_close_open_protocol_tasks(conn, sid, task=session.get("task", ""))
+        closed_task_ids.extend(closed_tasks)
 
         if draft:
             promote_draft_to_diary(sid, draft, task=session.get("task", ""))
@@ -196,7 +229,10 @@ def main():
     os.makedirs(os.path.dirname(AUTO_CLOSE_LOG), exist_ok=True)
     with open(AUTO_CLOSE_LOG, "a") as f:
         ts = datetime.datetime.now().isoformat(timespec="seconds")
-        f.write(f"{ts} — auto-closed {len(orphans)} session(s): {[s['sid'] for s in orphans]}\n")
+        f.write(
+            f"{ts} — auto-closed {len(orphans)} session(s): {[s['sid'] for s in orphans]} "
+            f"and {len(closed_task_ids)} protocol task(s): {closed_task_ids}\n"
+        )
 
 
 if __name__ == "__main__":

package/src/doctor/providers/runtime.py

@@ -704,10 +704,6 @@ def _client_assumption_regressions() -> list[str]:
     }
     offenders: list[str] = []
     for path in src_root.rglob("*.py"):
-        try:
-            text = path.read_text()
-        except Exception:
-            continue
         resolved = path.resolve()
         try:
             if resolved.is_relative_to(backup_root):
@@ -723,6 +719,12 @@ def _client_assumption_regressions() -> list[str]:
             relative_path = resolved.relative_to(src_root)
         except Exception:
             relative_path = path.relative_to(src_root)
+        if "versions" in relative_path.parts:
+            continue
+        try:
+            text = path.read_text()
+        except Exception:
+            continue
         if ".claude/projects" in text and relative_path not in allowed_relative_paths:
             offenders.append(f"{relative_path} hardcodes ~/.claude/projects")
     collect_path = src_root / "scripts" / "deep-sleep" / "collect.py"

package/src/hook_guardrails.py

@@ -13,7 +13,7 @@ from pathlib import Path
 import paths
 
 from core_prompts import render_core_prompt
-from db import create_protocol_debt, get_db, get_last_heartbeat_ts
+from db import create_protocol_debt, create_protocol_task, get_db, get_last_heartbeat_ts
 from operator_language import append_operator_language_contract
 from plugins.guard import _load_conditioned_learnings, _normalize_path_token
 from protocol_settings import get_protocol_strictness
@@ -429,6 +429,42 @@ def _strict_write_without_task_severity(session_id: str) -> str:
     return "error"
 
 
+def _auto_task_open_enabled() -> bool:
+    return os.environ.get("NEXO_AUTO_TASK_OPEN", "1").strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _auto_open_protocol_task_for_write(*, sid: str, tool_name: str, operation: str, files: list[str]) -> dict | None:
+    if not sid or not _auto_task_open_enabled():
+        return None
+    task_type = "edit" if operation == "write" else "execute"
+    clean_files = [item for item in files if str(item or "").strip()]
+    target = ", ".join(clean_files[:3]) if clean_files else "unknown target"
+    if len(clean_files) > 3:
+        target += f", +{len(clean_files) - 3} more"
+    try:
+        return create_protocol_task(
+            sid,
+            f"Auto-opened {task_type} task for {tool_name} on {target}",
+            task_type=task_type,
+            area="auto",
+            context_hint="PreToolUse auto-task_open: write/delete attempted without a matching open task.",
+            files=clean_files,
+            plan=[
+                "Auto-opened because the agent attempted a write/delete before explicit task_open.",
+                "Verify the edit and close with evidence.",
+            ],
+            constraints=[
+                "Do not treat this auto-open as success evidence.",
+                "Close as done only after verification; otherwise close partial/failed.",
+            ],
+            verification_step="Run the relevant test or inspection and close with evidence.",
+            must_verify=True,
+            must_change_log=True,
+        )
+    except Exception:
+        return None
+
+
 def _resolve_runtime_path(path: str) -> Path:
     candidate = Path(str(path or "")).expanduser()
     if not candidate.is_absolute():
@@ -1599,6 +1635,24 @@ def process_pre_tool_event(payload: dict) -> dict:
             "status": "blocked",
         }
 
+    auto_opened_task = None
+    if files:
+        missing_task_files = [filepath for filepath in files if not _find_open_task_for_file(conn, sid, filepath)]
+        if missing_task_files:
+            auto_opened_task = _auto_open_protocol_task_for_write(
+                sid=sid,
+                tool_name=tool_name,
+                operation=op,
+                files=missing_task_files,
+            )
+    elif not _find_any_open_task(conn, sid):
+        auto_opened_task = _auto_open_protocol_task_for_write(
+            sid=sid,
+            tool_name=tool_name,
+            operation=op,
+            files=[],
+        )
+
     if not files:
         task = _find_any_open_task(conn, sid)
         if not task:
@@ -1628,6 +1682,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             "operation": op,
             "strictness": strictness,
             "blocks": blocks,
+            "auto_opened_task": auto_opened_task,
             "status": "blocked" if blocks else "clean",
         }
 
@@ -1711,6 +1766,7 @@ def process_pre_tool_event(payload: dict) -> dict:
         "operation": op,
         "strictness": strictness,
         "blocks": blocks,
+        "auto_opened_task": auto_opened_task,
         "status": "blocked" if blocks else "clean",
     }
 

package/src/hooks/post_edit_change_log.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""Best-effort PostToolUse change_log recorder for write tools.
+
+This hook records file edit visibility directly in the DB layer. It never
+calls MCP tools and never blocks the client pipeline.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+_DIR = Path(__file__).resolve().parent
+_SRC = _DIR.parent
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+
+
+def _short_tool_name(tool_name: str) -> str:
+    clean = str(tool_name or "").strip()
+    return clean.rsplit("__", 1)[-1] if "__" in clean else clean
+
+
+def _read_stdin_json() -> dict:
+    if sys.stdin.isatty():
+        return {}
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return {}
+        payload = json.loads(raw)
+        return payload if isinstance(payload, dict) else {}
+    except Exception:
+        return {}
+
+
+def _tool_input(payload: dict) -> dict:
+    value = payload.get("tool_input") or payload.get("toolInput") or payload.get("input") or {}
+    return value if isinstance(value, dict) else {}
+
+
+def _extract_file_paths(payload: dict) -> list[str]:
+    tool_input = _tool_input(payload)
+    candidates: list[str] = []
+    for key in ("file_path", "filePath", "path", "notebook_path", "notebookPath"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            candidates.append(value.strip())
+    for key in ("file_paths", "filePaths", "paths"):
+        value = tool_input.get(key)
+        if isinstance(value, list):
+            candidates.extend(str(item).strip() for item in value if str(item).strip())
+    seen: set[str] = set()
+    paths: list[str] = []
+    for item in candidates:
+        if item in seen:
+            continue
+        seen.add(item)
+        paths.append(item)
+    return paths
+
+
+def _resolve_sid_from_payload(payload: dict) -> str:
+    candidates: list[str] = []
+    for key in ("nexo_sid", "sid", "session_id", "sessionId"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            candidates.append(value.strip())
+    for key in ("NEXO_SID", "CLAUDE_SESSION_ID"):
+        value = os.environ.get(key, "").strip()
+        if value:
+            candidates.append(value)
+    try:
+        from db import resolve_sid_from_external
+    except Exception:
+        return ""
+    for candidate in candidates:
+        if candidate.startswith("nexo-"):
+            return candidate
+        resolved = resolve_sid_from_external(candidate)
+        if resolved:
+            return resolved
+    return ""
+
+
+def record_post_edit_change(payload: dict) -> dict:
+    """Record a minimal change_log row for write-like tool payloads."""
+    tool_name = _short_tool_name(str(payload.get("tool_name") or payload.get("toolName") or ""))
+    if tool_name not in WRITE_TOOLS:
+        return {"ok": True, "skipped": True, "reason": "tool_not_write"}
+    if os.environ.get("NEXO_AUTO_CHANGE_LOG", "1").strip().lower() in {"0", "false", "no", "off"}:
+        return {"ok": True, "skipped": True, "reason": "disabled"}
+
+    paths = _extract_file_paths(payload)
+    if not paths:
+        return {"ok": True, "skipped": True, "reason": "missing_file_path"}
+
+    try:
+        from db import init_db, log_change
+    except Exception as exc:
+        return {"ok": False, "error": f"db_import_failed: {exc}"}
+
+    try:
+        init_db()
+        sid = _resolve_sid_from_payload(payload) or "unknown"
+        files = ", ".join(paths)
+        result = log_change(
+            sid,
+            files,
+            f"Auto-recorded PostToolUse {tool_name} file edit",
+            "PostToolUse observed a file write; recording traceability even if the agent forgets nexo_change_log.",
+            triggered_by="post_edit_change_log.py",
+            affects=files,
+            risks="Automatic trace only; verify the actual diff and tests separately.",
+            verify="Inspect git diff and run the relevant tests for the edited file.",
+            commit_ref="",
+        )
+        if "error" in result:
+            return {"ok": False, "error": result["error"]}
+        return {"ok": True, "change_log_id": result.get("id"), "files": paths}
+    except Exception as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+def main() -> int:
+    record_post_edit_change(_read_stdin_json())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/hooks/post_tool_use.py

@@ -208,6 +208,21 @@ def _run_auto_capture(payload: dict) -> int:
         return 1
 
 
+def _run_post_edit_change_log(payload: dict) -> int:
+    """Record write-tool visibility without calling MCP from the hook."""
+    try:
+        proc = subprocess.run(
+            ["python3", str(_DIR / "post_edit_change_log.py")],
+            input=json.dumps(payload),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return proc.returncode
+    except Exception:
+        return 1
+
+
 def main() -> int:
     started = time.time()
     payload = _read_stdin_json()
@@ -231,6 +246,7 @@ def main() -> int:
             protocol_message = stdout
 
     exits.append(_run_auto_capture(payload))
+    exits.append(_run_post_edit_change_log(payload))
 
     # v6.0.1 — inbox autodetect runs LAST so it sees the latest DB state
     # (including any writes the previous steps may have done). Emits a

package/src/plugins/update.py

@@ -16,6 +16,7 @@ from runtime_versioning import (
     activate_versioned_runtime_snapshot,
     compute_mcp_runtime_fingerprint,
     installed_force_restart_flag,
+    prune_old_versioned_runtime_snapshots,
     write_restart_required_marker,
 )
 
@@ -1236,6 +1237,7 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
 
     versioned_runtime_summary = None
     restart_marker_summary = None
+    version_prune_summary = None
     mcp_code_changed = False
     force_restart = False
     new_fingerprint = ""
@@ -1246,6 +1248,10 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
                 source_root=_runtime_code_root(),
                 version=new_version,
             )
+            version_prune_summary = prune_old_versioned_runtime_snapshots(
+                keep=2,
+                active_version=new_version,
+            )
         except Exception as e:
             errors.append(f"versioned runtime activation: {e}")
         # Decide whether the new release actually altered any MCP-loaded
@@ -1346,6 +1352,10 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
             lines.append(f"  WARNING: launchagent reload: {launchagent_reload_warning}")
     if versioned_runtime_summary and versioned_runtime_summary.get("ok"):
         lines.append(f"  Runtime activation: core/current -> versions/{new_version}")
+    if version_prune_summary and version_prune_summary.get("pruned"):
+        lines.append(
+            f"  Cleanup: pruned {len(version_prune_summary['pruned'])} old runtime version snapshot(s)"
+        )
     if restart_marker_summary:
         lines.append(f"  Restart marker: {restart_marker_summary.get('path')}")
     lines.append("")
@@ -1579,6 +1589,7 @@ def handle_update(
 
         versioned_runtime_summary = None
         restart_marker_summary = None
+        version_prune_summary = None
         mcp_code_changed = False
         force_restart = False
         new_fingerprint = ""
@@ -1589,6 +1600,10 @@ def handle_update(
                     source_root=SRC_DIR,
                     version=new_version,
                 )
+                version_prune_summary = prune_old_versioned_runtime_snapshots(
+                    keep=2,
+                    active_version=new_version,
+                )
                 steps_done.append("versioned-runtime")
             except Exception as e:
                 raise RuntimeError(f"Versioned runtime activation failed: {e}")
@@ -1662,6 +1677,10 @@ def handle_update(
             lines.append("  Clients: configured client targets synced")
         if versioned_runtime_summary and versioned_runtime_summary.get("ok"):
             lines.append(f"  Runtime activation: core/current -> versions/{new_version}")
+        if version_prune_summary and version_prune_summary.get("pruned"):
+            lines.append(
+                f"  Cleanup: pruned {len(version_prune_summary['pruned'])} old runtime version snapshot(s)"
+            )
         if restart_marker_summary:
             lines.append(f"  Restart marker: {restart_marker_summary.get('path')}")
         lines.append("")

package/src/runtime_versioning.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 import hashlib
 import json
 import os
+import re
 import shutil
 import time
 from dataclasses import dataclass
@@ -539,6 +541,67 @@ def activate_versioned_runtime_snapshot(*, source_root: Path | None = None, vers
     }
 
 
+def _runtime_version_sort_key(path: Path) -> tuple:
+    parts = re.split(r"([0-9]+)", path.name)
+    key = []
+    for part in parts:
+        if not part:
+            continue
+        if part.isdigit():
+            key.append((0, int(part)))
+        else:
+            key.append((1, part.lower()))
+    return tuple(key)
+
+
+def _active_version_name() -> str:
+    current = core_current_link()
+    if current.exists() or current.is_symlink():
+        with contextlib.suppress(Exception):
+            resolved = current.resolve(strict=False)
+            if resolved.parent.name == "versions":
+                return resolved.name
+    return installed_runtime_version()
+
+
+def prune_old_versioned_runtime_snapshots(*, keep: int = 2, active_version: str = "") -> dict:
+    """Remove runtime snapshots older than the active + newest ``keep`` versions."""
+    keep = max(int(keep or 0), 1)
+    versions_dir = core_versions_dir()
+    report = {
+        "ok": True,
+        "versions_dir": str(versions_dir),
+        "keep": keep,
+        "active_version": str(active_version or "").strip(),
+        "kept": [],
+        "pruned": [],
+        "errors": [],
+    }
+    if not versions_dir.is_dir():
+        return report
+
+    snapshots = [item for item in versions_dir.iterdir() if item.is_dir() and not item.is_symlink()]
+    snapshots.sort(key=_runtime_version_sort_key)
+    active = str(active_version or _active_version_name() or "").strip()
+    report["active_version"] = active
+
+    keep_names = {item.name for item in snapshots[-keep:]}
+    if active:
+        keep_names.add(active)
+
+    for snapshot in snapshots:
+        if snapshot.name in keep_names:
+            report["kept"].append(snapshot.name)
+            continue
+        try:
+            shutil.rmtree(snapshot)
+            report["pruned"].append(snapshot.name)
+        except Exception as exc:
+            report["ok"] = False
+            report["errors"].append({"version": snapshot.name, "error": str(exc)})
+    return report
+
+
 def clear_restart_required_marker(
     *,
     client: str = "",

package/src/script_registry.py

@@ -95,6 +95,24 @@ SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
 SUPPORTED_RECOVERY_POLICIES = {"none", "run_once_on_wake", "catchup", "restart", "restart_daemon"}
 PERSONAL_SCRIPT_FILENAME_PREFIX = "ps-"
+_RUNTIME_METADATA_ALIASES = {
+    "bash": "shell",
+    "sh": "shell",
+    "zsh": "shell",
+    "shellscript": "shell",
+    "python3": "python",
+    "py": "python",
+    "nodejs": "node",
+    "javascript": "node",
+}
+_SCHEDULE_WEEKDAY_SUFFIX_RE = re.compile(
+    r"^(?P<hour>\d{1,2}):(?P<minute>\d{2})\s+weekday\s*=\s*(?P<weekday>\d)$",
+    re.IGNORECASE,
+)
+_SCHEDULE_WEEKDAY_PREFIX_RE = re.compile(
+    r"^weekday\s*=\s*(?P<weekday>\d)\s+(?P<hour>\d{1,2}):(?P<minute>\d{2})$",
+    re.IGNORECASE,
+)
 _LEGACY_CORE_SCRIPT_ALIASES = {
     "nexo-postcompact.sh": "post-compact.sh",
     "nexo-memory-precompact.sh": "pre-compact.sh",
@@ -341,10 +359,40 @@ def parse_inline_metadata(path: Path) -> dict:
         key, value = payload.split("=", 1)
         k = key.strip()
         if k in METADATA_KEYS:
-            meta[k] = value.strip()
+            meta[k] = _normalize_metadata_value(k, value.strip())
     return meta
 
 
+def _normalize_metadata_value(key: str, value: str) -> str:
+    if key == "runtime":
+        return _normalize_runtime_metadata(value)
+    if key == "schedule":
+        return _normalize_schedule_metadata(value)
+    return value
+
+
+def _normalize_runtime_metadata(value: str) -> str:
+    candidate = str(value or "").strip().lower()
+    return _RUNTIME_METADATA_ALIASES.get(candidate, candidate)
+
+
+def _normalize_schedule_metadata(value: str) -> str:
+    candidate = re.sub(r"\s+", " ", str(value or "").strip())
+    for pattern in (_SCHEDULE_WEEKDAY_SUFFIX_RE, _SCHEDULE_WEEKDAY_PREFIX_RE):
+        match = pattern.match(candidate)
+        if not match:
+            continue
+        try:
+            hour = int(match.group("hour"))
+            minute = int(match.group("minute"))
+            weekday = int(match.group("weekday"))
+        except ValueError:
+            return candidate
+        if 0 <= hour <= 23 and 0 <= minute <= 59 and 0 <= weekday <= 6:
+            return f"{hour:02d}:{minute:02d}:{weekday}"
+    return candidate
+
+
 def _detect_shebang(path: Path) -> str | None:
     """Read first line for shebang."""
     try:
@@ -1068,6 +1116,169 @@ def _canonical_schedule_value(schedule_type: str, schedule_value: str | dict | l
     return str(schedule_value or "")
 
 
+def _metadata_comment_prefix(path: Path) -> str:
+    return "//" if path.suffix.lower() == ".js" else "#"
+
+
+def _compact_schedule_from_record(record: dict) -> str:
+    raw = str(record.get("schedule_value") or "").strip()
+    if not raw:
+        return ""
+    payload = None
+    if raw.lstrip().startswith("{") or raw.lstrip().startswith("["):
+        with contextlib.suppress(Exception):
+            payload = json.loads(raw)
+    if isinstance(payload, list):
+        payload = payload[0] if len(payload) == 1 and isinstance(payload[0], dict) else None
+    if isinstance(payload, dict):
+        hour = payload.get("Hour")
+        minute = payload.get("Minute")
+        weekday = payload.get("Weekday")
+        try:
+            hour_i = int(hour)
+            minute_i = int(minute)
+            weekday_i = int(weekday) if weekday is not None else None
+        except (TypeError, ValueError):
+            return ""
+        if not (0 <= hour_i <= 23 and 0 <= minute_i <= 59):
+            return ""
+        if weekday_i is not None:
+            if not (0 <= weekday_i <= 6):
+                return ""
+            return f"{hour_i:02d}:{minute_i:02d}:{weekday_i}"
+        return f"{hour_i:02d}:{minute_i:02d}"
+
+    normalized = _normalize_schedule_metadata(raw)
+    if _calendar_payload_from_declared(normalized) is not None:
+        return normalized
+
+    label = str(record.get("schedule_label") or "").strip()
+    match = re.search(r"(?P<hour>\d{1,2}):(?P<minute>\d{2})(?:\s+weekday=(?P<weekday>\d))?", label)
+    if not match:
+        return ""
+    weekday_part = f":{match.group('weekday')}" if match.group("weekday") is not None else ""
+    return f"{int(match.group('hour')):02d}:{int(match.group('minute')):02d}{weekday_part}"
+
+
+def _inferred_schedule_metadata_lines(path: Path, metadata: dict, record: dict) -> list[str] | None:
+    schedule_type = str(record.get("schedule_type") or "")
+    if schedule_type not in {"interval", "calendar", "keep_alive"}:
+        return None
+
+    name = _logical_personal_script_name(str(metadata.get("name") or path.stem))
+    description = str(metadata.get("description") or "Personal automation managed by NEXO").strip()
+    runtime = classify_runtime(path, metadata)
+    if runtime == "unknown":
+        runtime = "shell" if path.suffix.lower() == ".sh" else "python"
+    cron_id = _safe_slug(str(record.get("cron_id") or metadata.get("cron_id") or name))
+    prefix = _metadata_comment_prefix(path)
+
+    lines = [
+        f"{prefix} nexo: name={name}",
+        f"{prefix} nexo: description={description}",
+        f"{prefix} nexo: runtime={runtime}",
+        f"{prefix} nexo: cron_id={cron_id}",
+        f"{prefix} nexo: schedule_required=true",
+    ]
+    if schedule_type == "interval":
+        try:
+            interval = int(str(record.get("schedule_value") or "").strip())
+        except ValueError:
+            return None
+        if interval <= 0:
+            return None
+        lines.append(f"{prefix} nexo: interval_seconds={interval}")
+        lines.append(f"{prefix} nexo: recovery_policy=run_once_on_wake")
+    elif schedule_type == "calendar":
+        compact_schedule = _compact_schedule_from_record(record)
+        if not compact_schedule:
+            return None
+        lines.append(f"{prefix} nexo: schedule={compact_schedule}")
+        lines.append(f"{prefix} nexo: recovery_policy=catchup")
+    elif schedule_type == "keep_alive":
+        lines.append(f"{prefix} nexo: recovery_policy=restart_daemon")
+
+    if record.get("run_at_load"):
+        lines.append(f"{prefix} nexo: run_on_boot=true")
+    return lines
+
+
+def _write_metadata_block(path: Path, metadata_lines: list[str]) -> None:
+    raw = path.read_text(errors="ignore")
+    lines = raw.splitlines(keepends=True)
+    insert_at = 1 if lines and lines[0].startswith("#!") else 0
+    filtered: list[str] = []
+    for index, line in enumerate(lines):
+        stripped = line.lstrip()
+        if index >= insert_at and index < 25 and (
+            stripped.startswith("# nexo:") or stripped.startswith("// nexo:")
+        ):
+            continue
+        filtered.append(line)
+    block = [line.rstrip("\n") + "\n" for line in metadata_lines]
+    filtered[insert_at:insert_at] = block
+    path.write_text("".join(filtered))
+
+
+def repair_orphan_personal_schedule_metadata(*, dry_run: bool = False) -> dict:
+    """Infer inline metadata for personal LaunchAgents that predate the registry.
+
+    This powers ``nexo doctor --fix`` and ``nexo scripts reconcile`` for the
+    legacy case where a user-owned LaunchAgent exists but the script has no
+    declared schedule metadata. It never touches scripts outside the personal
+    scripts directory.
+    """
+    classification = classify_scripts_dir()
+    personal_scripts = [entry for entry in classification["entries"] if entry["classification"] == "personal"]
+    scripts_by_path = {
+        str(Path(entry["path"]).expanduser().resolve(strict=False)): entry
+        for entry in personal_scripts
+    }
+    report = {
+        "ok": True,
+        "dry_run": dry_run,
+        "repaired": [],
+        "skipped": [],
+        "errors": [],
+    }
+    for record in _discover_personal_schedule_records():
+        script_path = str(record.get("script_path") or "")
+        if not script_path:
+            report["skipped"].append({"cron_id": record.get("cron_id", ""), "reason": "missing script path"})
+            continue
+        resolved_path = str(Path(script_path).expanduser().resolve(strict=False))
+        script = scripts_by_path.get(resolved_path)
+        if not script:
+            report["skipped"].append({"cron_id": record.get("cron_id", ""), "path": script_path, "reason": "not a registered personal script"})
+            continue
+        declared = script.get("declared_schedule", {})
+        if declared.get("required") and declared.get("valid"):
+            report["skipped"].append({"cron_id": record.get("cron_id", ""), "path": script_path, "reason": "already has valid schedule metadata"})
+            continue
+        path = Path(script["path"])
+        metadata_lines = _inferred_schedule_metadata_lines(path, script.get("metadata", {}), record)
+        if not metadata_lines:
+            report["skipped"].append({"cron_id": record.get("cron_id", ""), "path": script_path, "reason": "unsupported schedule metadata inference"})
+            continue
+        entry = {
+            "cron_id": str(record.get("cron_id") or ""),
+            "path": str(path),
+            "schedule_type": str(record.get("schedule_type") or ""),
+        }
+        if dry_run:
+            entry["dry_run"] = True
+            report["repaired"].append(entry)
+            continue
+        try:
+            _write_metadata_block(path, metadata_lines)
+            report["repaired"].append(entry)
+        except Exception as exc:
+            report["errors"].append({"path": str(path), "error": str(exc)})
+    if report["errors"]:
+        report["ok"] = False
+    return report
+
+
 def _extract_launchctl_value(output: str, prefixes: str | tuple[str, ...]) -> str | None:
     if isinstance(prefixes, str):
         prefixes = (prefixes,)
@@ -1605,12 +1816,14 @@ def ensure_personal_schedules(*, dry_run: bool = False) -> dict:
 def reconcile_personal_scripts(*, dry_run: bool = False) -> dict:
     """Full lifecycle reconciliation: classify, sync registry, ensure declared schedules."""
     renamed_result = rename_legacy_personal_script_filenames(dry_run=dry_run)
+    orphan_metadata_result = repair_orphan_personal_schedule_metadata(dry_run=dry_run)
     sync_result = sync_personal_scripts()
     ensure_result = ensure_personal_schedules(dry_run=dry_run)
     return {
         "ok": True,
         "dry_run": dry_run,
         "renamed_legacy_filenames": renamed_result,
+        "repaired_orphan_schedule_metadata": orphan_metadata_result,
         "sync": sync_result,
         "marker_warnings": sync_result.get("marker_warnings", []),
         "ensure_schedules": ensure_result,

package/src/scripts/nexo-email-monitor.py

@@ -6,7 +6,7 @@
 # nexo: cron_id=email-monitor
 # nexo: interval_seconds=60
 # nexo: schedule_required=true
-# nexo: timeout=21600
+# nexo: timeout=1800
 # nexo: recovery_policy=run_once_on_wake
 # nexo: run_on_boot=false
 # nexo: run_on_wake=true

package/src/scripts/nexo-followup-runner.py

@@ -3,7 +3,7 @@
 # nexo: description=Continuous NEXO pending-work runner. Executes due followups, avoids overlap, and escalates operator attention through reminders/orchestrator.
 # nexo: category=automation
 # nexo: runtime=python
-# nexo: timeout=21600
+# nexo: timeout=10800
 # nexo: cron_id=followup-runner
 # nexo: interval_seconds=3600
 # nexo: schedule_required=true
@@ -20,7 +20,7 @@ NEXO Followup Runner v8 — continuous pending-work runner.
 Role:
 1. Pick up due or recurring followups that should already be running.
 2. Process them through the real NEXO runtime and its MCP surface.
-3. Avoid overlap via lock + long timeout (6h).
+3. Avoid overlap via lock + bounded timeout.
 4. Escalate operator attention through standard NEXO reminders when needed.
 
 From the operator's point of view, these are all "pending items". Internally,
@@ -58,6 +58,7 @@ from automation_controls import (
     get_send_reply_script_path,
 )
 from client_preferences import resolve_automation_backend, resolve_client_runtime_profile
+from constants import AUTOMATION_SUBPROCESS_TIMEOUT
 from core_prompts import render_core_prompt
 from operator_language import build_operator_language_contract, normalize_operator_language
 import db as nexo_db
@@ -69,7 +70,7 @@ LOG_FILE = LOG_DIR / "followup-runner.log"
 STATE_FILE = data_dir() / "followup-state.json"
 RESULTS_FILE = data_dir() / "followup-runner-results.json"
 
-CLI_TIMEOUT = 21600  # 6h safety net
+CLI_TIMEOUT = AUTOMATION_SUBPROCESS_TIMEOUT
 LOCK_FILE = LOG_DIR / "followup-runner.lock"
 MAX_FOLLOWUPS_PER_RUN = 5  # Focus: Opus can actually execute 5, not 30
 COOLDOWN_DAYS = 3  # Don't retry needs_decision/blocked for 3 days

package/src/tree_hygiene.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 """Shared tree hygiene helpers for runtime/install/release flows."""
 
 import re
+import os
 from pathlib import Path
 
 
@@ -46,11 +47,11 @@ def find_duplicate_artifact_paths(root: str | Path) -> list[Path]:
     """Find duplicate copy artifacts under a tree, skipping generated/vendor directories."""
     root_path = Path(root).resolve()
     duplicates: list[Path] = []
-    for path in sorted(root_path.rglob("*")):
-        if any(part in _IGNORED_DIRS for part in path.parts):
-            continue
-        if not path.is_file():
-            continue
-        if is_duplicate_artifact_name(path):
-            duplicates.append(path)
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        dirnames[:] = sorted(name for name in dirnames if name not in _IGNORED_DIRS)
+        current = Path(dirpath)
+        for filename in sorted(filenames):
+            path = current / filename
+            if is_duplicate_artifact_name(path):
+                duplicates.append(path)
     return duplicates