nexo-brain 7.1.10 → 7.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.1.10",
+  "version": "7.2.0",
   "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.1.10` is the current packaged-runtime line. It is a follow-up over v7.1.8 that ships two rescue batches of WIP that were stashed aside during the v7.1.8 release window. First rescue: `src/autonomy_mandate.py` expands the mandate-detection vocabulary (hazlo todo / no pares / estás al mando / te dejo al mando / sigue sin parar / haz el plan completo), adds three honest flags on `MandateState` (`execute_until_blocker`, `suppress_mid_task_menus`, `revalidate_after_compaction`) with session filtering, wires post/pre-compact hooks that read those flags, surfaces them through protocol/workflow handlers and session payload, and introduces the new `src/checkpoint_policy.py` module with tests. Second rescue: `scripts/verify_release_readiness.py` gains a smoke-artifact contract pass that validates `release-contracts/smoke/v<version>.json` before any tag push, the release-final audit skill references the new contract, `src/hook_guardrails.py` + `src/hooks/post_tool_use.py` refine the post-tool protocol reminder path with a new contract test, and a couple of core prompts (task-close evidence, r14 correction learning) get wording polish. Both rescues are orthogonal to v7.1.8 and fully covered by tests.
+Version `7.2.0` is the current packaged-runtime line. It is a minor release that consolidates three parallel workstreams into a single Guardian-active-by-default train. Block K roadmap closure: G1 enforcer active (PostToolUse nudge when the latest `nexo_task_open` returned `mode ∈ {defer, ask, verify}` and the operator has not executed the paired `next_action`), G3 SSH remote-write detector (catches `ssh host "cat > ..."`, `scp upload`, `rsync upload`, `sftp -b batch` and 10+ other patterns the local destructive gate never saw), new `src/guardian_runtime_config.py` resolver (env > `~/.nexo/personal/config/guardian-runtime-overrides.json` > default), and `_persist_guardian_hard_defaults` during `nexo update` so every non-ephemeral install gets Guardian in `hard` without manual env vars. F0.6 hardening wave: `nexo rollback f06` CLI with two-stage safe swap, `src/scripts/prune_runtime_backups.py` promoted from personal to core, the authoritative `docs/f06-layout-contract.md`, three new doctor boot-tier checks (`check_core_dev_packaged_install`, `check_dashboard_desktop_contract`, `check_f06_migration_consistency`), `scripts/nexo-migrate-nora.sh` + `scripts/f0-safe-apply-remote.sh` idempotent migration workflow, and v6.x→F0.6 rollback hardening tests. Adaptive weights: flips from "14-day calendar wait" to "14 days OR (≥200 samples AND ≥2 days)" + `_maybe_promote_adaptive_weights_empirically` auto-promotes shadow→learned during `nexo update` so mature installs feel the Cortex calibration immediately. Small-fixes batch: R34 `bool("unknown")==True` fix, `classify_scripts_dir` dedup by realpath, B10 module-level path constants lazy-evaluated in `public_contribution.py` / `tools_sessions.py` / `plugins/recover.py` / `plugins/update.py`, schedule override audit log at `runtime/logs/core-schedule-overrides.log`, `scripts/pre-release-verify.sh` + `docs/release-discipline.md`, and a pre-commit hook that blocks commits when `tool-enforcement-map.json` drifts from `src/plugins/`.
+
+Previously in `7.1.10`: follow-up over v7.1.8 that shipped two rescue batches of WIP stashed aside during the v7.1.8 release window. First rescue: `src/autonomy_mandate.py` expanded the mandate-detection vocabulary (hazlo todo / no pares / estás al mando / te dejo al mando / sigue sin parar / haz el plan completo), added three honest flags on `MandateState` (`execute_until_blocker`, `suppress_mid_task_menus`, `revalidate_after_compaction`) with session filtering, wired post/pre-compact hooks that read those flags, surfaced them through protocol/workflow handlers and session payload, and introduced the new `src/checkpoint_policy.py` module with tests. Second rescue: `scripts/verify_release_readiness.py` gained a smoke-artifact contract pass that validates `release-contracts/smoke/v<version>.json` before any tag push, the release-final audit skill references the new contract, `src/hook_guardrails.py` + `src/hooks/post_tool_use.py` refine the post-tool protocol reminder path with a new contract test, and a couple of core prompts (task-close evidence, r14 correction learning) got wording polish.
 
 Previously in `7.1.8`: batch release over v7.1.7 consolidating the Block K Guardian/Enforcer roadmap (auto-drain of stale `protocol_debt` rows, destructive-command pre-tool gate, `guard_check`-required gate, inline guard ack on `nexo_task_open`, Guardian Health in the morning briefing) with Block D hardcode cleanup (classifier-backed `backfill_task_owner`, migration v50 supersedes the duplicate NEXO-product learning pair, new semantic-hardcodes audit) and Block E product guards (LaunchAgent plist protection, agent-name fallbacks no longer leak the product identity, `francisco_emails` removed from the email-config dict export, `runner-health-check.py` + `nexo_personal_automation.py` promoted from personal to core).
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "7.1.10",
+  "version": "7.2.0",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO Brain — 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.",
+  "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",
   "bin": {
     "nexo-brain": "./bin/nexo-brain.js",

package/src/auto_update.py

@@ -389,25 +389,65 @@ def _write_last_check(data: dict):
 
 
 def _sync_watchdog_hash_registry():
-    """Keep the immutable-hash registry aligned with the installed watchdog script."""
+    """Keep the immutable-hash registry aligned with the installed watchdog script.
+
+    Folds any pre-F0.6 legacy registry at ``paths.legacy_watchdog_hashes_path()``
+    into the canonical F0.6 file and then drops the legacy artifact so a later
+    ``ls ~/.nexo/scripts/.watchdog-hashes`` is empty (unless ``~/.nexo/scripts``
+    is itself a symlink to the canonical dir, in which case both paths already
+    point at the same inode).
+    """
     try:
         watchdog_file = paths.core_scripts_dir() / "nexo-watchdog.sh"
         if not watchdog_file.exists():
             return
         registry_file = paths.core_scripts_dir() / ".watchdog-hashes"
+        legacy_registry_file = paths.legacy_watchdog_hashes_path()
         entries: dict[str, str] = {}
-        if registry_file.exists():
-            for line in registry_file.read_text().splitlines():
-                if "|" not in line:
-                    continue
-                filepath, expected = line.split("|", 1)
-                if filepath:
-                    entries[filepath] = expected
+
+        def _load(path: Path) -> None:
+            if not path.exists():
+                return
+            try:
+                for line in path.read_text().splitlines():
+                    if "|" not in line:
+                        continue
+                    filepath, expected = line.split("|", 1)
+                    if filepath:
+                        entries[filepath] = expected
+            except Exception as load_error:
+                _log(f"watchdog hash registry load error at {path}: {load_error}")
+
+        _load(registry_file)
+
+        legacy_is_canonical_alias = False
+        if legacy_registry_file.exists():
+            try:
+                legacy_is_canonical_alias = (
+                    registry_file.exists()
+                    and legacy_registry_file.resolve() == registry_file.resolve()
+                )
+            except Exception:
+                legacy_is_canonical_alias = False
+            if not legacy_is_canonical_alias:
+                _load(legacy_registry_file)
+
         actual_hash = hashlib.sha256(watchdog_file.read_bytes()).hexdigest()
         entries[str(watchdog_file)] = actual_hash
         registry_file.write_text(
             "\n".join(f"{filepath}|{digest}" for filepath, digest in sorted(entries.items())) + "\n"
         )
+
+        if (
+            legacy_registry_file.exists()
+            and not legacy_is_canonical_alias
+            and legacy_registry_file != registry_file
+        ):
+            try:
+                legacy_registry_file.unlink()
+                _log(f"watchdog hash registry migrated from legacy path: {legacy_registry_file}")
+            except Exception as unlink_error:
+                _log(f"watchdog hash registry legacy cleanup skipped: {unlink_error}")
     except Exception as e:
         _log(f"watchdog hash registry sync error: {e}")
 
@@ -4608,6 +4648,26 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     except Exception as exc:
         actions.append(f"classifier-install-warning:{exc.__class__.__name__}")
 
+    try:
+        _emit_progress(progress_fn, "Persisting Guardian enforcement defaults...")
+        persisted, persist_message = _persist_guardian_hard_defaults(dest)
+        if persisted:
+            actions.append("guardian-hard-persisted")
+        if persist_message:
+            actions.append(persist_message)
+    except Exception as exc:
+        actions.append(f"guardian-hard-persist-warning:{exc.__class__.__name__}")
+
+    try:
+        _emit_progress(progress_fn, "Promoting adaptive weights if enough data...")
+        promoted, promote_message = _maybe_promote_adaptive_weights_empirically(dest)
+        if promoted:
+            actions.append("adaptive-weights-promoted")
+        if promote_message:
+            actions.append(promote_message)
+    except Exception as exc:
+        actions.append(f"adaptive-weights-promote-warning:{exc.__class__.__name__}")
+
     _emit_progress(progress_fn, "Verifying runtime imports...")
     verify = subprocess.run(
         [sys.executable, "-c", "import server"],
@@ -4655,6 +4715,177 @@ def _emit_progress(progress_fn, message: str) -> None:
             pass
 
 
+_GUARDIAN_PERSIST_HARD_DEFAULTS = {
+    "G1_ENFORCER_ACTIVE": "hard",
+    "G3_ENFORCE_DESTRUCTIVE": "hard",
+    "G3_SSH_ENFORCE_REMOTE_WRITE": "hard",
+    "G4_ENFORCE_GUARD_CHECK": "hard",
+}
+
+
+def _persist_guardian_hard_defaults(dest: Path) -> tuple[bool, str | None]:
+    """Write ``~/.nexo/config/guardian-runtime-overrides.json`` with the
+    v7.2.0 "Guardian-on by default" matrix so operators get the active
+    enforcer experience without setting env vars every shell.
+
+    Returns (persisted, message). ``persisted`` is True when the file was
+    written or updated during this call; False when we left it alone
+    (operator opt-out, or file already matches the defaults).
+
+    Contract:
+        - Operator opt-out with ``NEXO_GUARDIAN_PERSIST_HARD=off`` in env
+          at update time: leave the file untouched.
+        - Ephemeral runtimes: skip.
+        - Never overwrite a key the operator already customized to a
+          non-default value (``shadow`` / ``off`` / anything else). Only
+          fills missing keys or upgrades explicit defaults.
+    """
+    if _is_ephemeral_runtime_install(dest):
+        return False, "guardian-hard-persist-skipped:ephemeral"
+    if os.environ.get("NEXO_GUARDIAN_PERSIST_HARD", "").strip().lower() == "off":
+        return False, "guardian-hard-persist-skipped:operator-opt-out"
+
+    config_path = dest / "personal" / "config" / "guardian-runtime-overrides.json"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    current: dict[str, str] = {}
+    if config_path.is_file():
+        try:
+            raw = json.loads(config_path.read_text())
+            if isinstance(raw, dict):
+                current = {str(k): str(v) for k, v in raw.items()}
+        except Exception:
+            # Malformed file — treat as empty. We write the fresh defaults
+            # and keep the malformed copy for the operator to inspect.
+            try:
+                config_path.rename(
+                    config_path.with_suffix(
+                        config_path.suffix + f".broken-{int(time.time())}"
+                    )
+                )
+            except Exception:
+                pass
+            current = {}
+
+    original = dict(current)
+    for key, default in _GUARDIAN_PERSIST_HARD_DEFAULTS.items():
+        if key not in current:
+            current[key] = default
+
+    if current == original and config_path.is_file():
+        return False, None
+
+    try:
+        tmp_path = config_path.with_suffix(config_path.suffix + ".tmp")
+        tmp_path.write_text(json.dumps(current, indent=2, ensure_ascii=False) + "\n")
+        tmp_path.replace(config_path)
+    except Exception as exc:  # pragma: no cover - filesystem failures
+        return False, f"guardian-hard-persist-error:{exc.__class__.__name__}"
+
+    return True, None
+
+
+from datetime import datetime as _adaptive_datetime  # isolated alias; other modules use ``time.time()``
+
+_ADAPTIVE_PROMOTE_MIN_SAMPLES = 200
+_ADAPTIVE_PROMOTE_MIN_DAYS = 2
+
+
+def _maybe_promote_adaptive_weights_empirically(dest: Path) -> tuple[bool, str | None]:
+    """Promote ``shadow_weights`` to ``learned_weights`` during ``nexo update``
+    when the install already has enough empirical signal.
+
+    Mirrors the empirical path in ``adaptive_mode.learn_weights`` (the
+    background learner cron). Without this, operators upgrading to v7.2.0
+    with a mature shadow dataset would still have to wait for the next
+    learner tick to feel the calibration — which can be hours or days.
+
+    Conditions to promote:
+        - adaptive_state.json exists and parses.
+        - ``shadow_weights`` dict is present.
+        - ``shadow_weights_samples >= 200`` AND the learner has been
+          running for at least 2 calendar days
+          (``learned_weights_first_date`` ≥ 2 days ago).
+        - ``learned_weights`` is absent or empty (never overwrite an
+          already-active set of weights).
+        - Operator opt-out flag ``NEXO_ADAPTIVE_EMPIRICAL_PROMOTION=off``
+          is NOT set. Same flag the learner already honours, so
+          operators who opted out stay opted out everywhere.
+
+    Returns ``(promoted, message)``:
+        - ``(True, None)``: weights were promoted, audit trail written.
+        - ``(False, None)``: no-op (no shadow data, not enough samples,
+          already promoted, or ephemeral install).
+        - ``(False, "adaptive-promote-skipped:<reason>")``: explicit skip
+          for the install log.
+    """
+    if _is_ephemeral_runtime_install(dest):
+        return False, "adaptive-promote-skipped:ephemeral"
+    if os.environ.get("NEXO_ADAPTIVE_EMPIRICAL_PROMOTION", "").strip().lower() == "off":
+        return False, "adaptive-promote-skipped:operator-opt-out"
+
+    state_path = dest / "personal" / "brain" / "adaptive_state.json"
+    if not state_path.is_file():
+        # Fall back to the legacy pre-F0.6 location for half-migrated
+        # installs; the migrator will eventually move it.
+        legacy = dest / "brain" / "adaptive_state.json"
+        if legacy.is_file():
+            state_path = legacy
+        else:
+            return False, None  # no data yet — nothing to promote
+
+    try:
+        raw = json.loads(state_path.read_text())
+    except Exception:
+        return False, "adaptive-promote-skipped:state-parse-error"
+    if not isinstance(raw, dict):
+        return False, "adaptive-promote-skipped:state-not-dict"
+
+    learned = raw.get("learned_weights")
+    if isinstance(learned, dict) and learned:
+        return False, None  # already active — nothing to do
+
+    shadow = raw.get("shadow_weights")
+    if not isinstance(shadow, dict) or not shadow:
+        return False, None  # no shadow data yet
+
+    samples = 0
+    try:
+        samples = int(raw.get("shadow_weights_samples", 0) or 0)
+    except (TypeError, ValueError):
+        samples = 0
+    if samples < _ADAPTIVE_PROMOTE_MIN_SAMPLES:
+        return False, None
+
+    first_date_raw = str(raw.get("learned_weights_first_date") or "").strip()
+    if not first_date_raw:
+        return False, None
+    try:
+        first_dt = _adaptive_datetime.strptime(first_date_raw[:19], "%Y-%m-%dT%H:%M:%S")
+    except ValueError:
+        return False, "adaptive-promote-skipped:first-date-parse-error"
+    days_since_first = (_adaptive_datetime.utcnow() - first_dt).days
+    if days_since_first < _ADAPTIVE_PROMOTE_MIN_DAYS:
+        return False, None
+
+    # Promote — deep-copy so callers holding references to the original
+    # dict don't see phantom mutations mid-update.
+    raw["learned_weights"] = {str(k): v for k, v in shadow.items()}
+    raw["learned_weights_date"] = _adaptive_datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
+    raw["learned_weights_samples"] = samples
+    raw["learned_weights_promoted_by"] = "nexo_update_empirical_v7_2_0"
+    raw["learned_weights_promoted_at"] = _adaptive_datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
+
+    try:
+        tmp_path = state_path.with_suffix(state_path.suffix + ".tmp")
+        tmp_path.write_text(json.dumps(raw, indent=2, ensure_ascii=False) + "\n")
+        tmp_path.replace(state_path)
+    except Exception as exc:  # pragma: no cover - filesystem failures
+        return False, f"adaptive-promote-error:{exc.__class__.__name__}"
+
+    return True, None
+
+
 def _parse_runtime_init_payload(stdout: str) -> dict:
     """Extract the JSON payload emitted by the runtime init helper."""
     lines = [line.strip() for line in stdout.splitlines() if line.strip()]

package/src/cli.py

@@ -1168,6 +1168,199 @@ def _recover(args):
     return _recover_cli_main(argv)
 
 
+def _rollback_f06(args):
+    """Revert the F0.6 layout migration using ``~/.nexo-pre-f06-snapshot``.
+
+    Safe two-stage swap: the current ``~/.nexo`` tree is renamed to a dated
+    backup (``~/.nexo-rollback-backup-YYYYMMDDHHMMSS``) BEFORE the snapshot is
+    restored in its place, so the operation never destroys state if it is
+    interrupted mid-way. LaunchAgents are booted out before the swap and
+    reloaded after (skip via ``--keep-agents-running``).
+    """
+    import json as _json
+    import shutil as _shutil
+    import subprocess as _subprocess
+    from datetime import datetime as _datetime
+    from pathlib import Path as _Path
+
+    nexo_home = _Path(os.environ.get("NEXO_HOME", str(_Path.home() / ".nexo")))
+    snapshot = _Path(str(nexo_home) + "-pre-f06-snapshot")
+    now_stamp = _datetime.now().strftime("%Y%m%d%H%M%S")
+    dry_run = bool(getattr(args, "dry_run", False))
+    emit_json = bool(getattr(args, "json", False))
+    assume_yes = bool(getattr(args, "yes", False))
+    keep_agents = bool(getattr(args, "keep_agents_running", False))
+
+    report: dict[str, object] = {
+        "nexo_home": str(nexo_home),
+        "snapshot": str(snapshot),
+        "snapshot_exists": snapshot.exists(),
+        "snapshot_is_dir": snapshot.is_dir() if snapshot.exists() else False,
+        "dry_run": dry_run,
+        "steps": [],
+        "status": "planned",
+    }
+
+    if not snapshot.exists() or not snapshot.is_dir():
+        report["status"] = "error_no_snapshot"
+        report["error"] = f"Pre-F0.6 snapshot not found at {snapshot}"
+        if emit_json:
+            print(_json.dumps(report, indent=2))
+        else:
+            print(f"ERROR: no pre-F0.6 snapshot at {snapshot}", file=sys.stderr)
+            print("       Rollback is only available immediately after a migration.", file=sys.stderr)
+        return 1
+
+    if nexo_home.exists():
+        backup_target = _Path(str(nexo_home) + f"-rollback-backup-{now_stamp}")
+        # Avoid collision if the operator retries in the same second.
+        collision_suffix = 0
+        while backup_target.exists():
+            collision_suffix += 1
+            backup_target = _Path(str(nexo_home) + f"-rollback-backup-{now_stamp}-{collision_suffix}")
+    else:
+        backup_target = None
+
+    agents_to_restart: list[_Path] = []
+    if not keep_agents:
+        agents_dir = _Path.home() / "Library" / "LaunchAgents"
+        if agents_dir.is_dir():
+            agents_to_restart = sorted(agents_dir.glob("com.nexo.*.plist"))
+
+    plan_steps: list[dict] = []
+    if agents_to_restart:
+        plan_steps.append({
+            "step": "bootout_launchagents",
+            "count": len(agents_to_restart),
+            "samples": [p.name for p in agents_to_restart[:5]],
+        })
+    if backup_target is not None:
+        plan_steps.append({
+            "step": "move_current_nexo_home_to_backup",
+            "from": str(nexo_home),
+            "to": str(backup_target),
+        })
+    plan_steps.append({
+        "step": "move_snapshot_to_nexo_home",
+        "from": str(snapshot),
+        "to": str(nexo_home),
+    })
+    if agents_to_restart:
+        plan_steps.append({
+            "step": "reload_launchagents",
+            "count": len(agents_to_restart),
+        })
+    report["steps"] = plan_steps
+
+    if dry_run:
+        report["status"] = "dry_run"
+        if emit_json:
+            print(_json.dumps(report, indent=2))
+        else:
+            print(f"nexo rollback f06 (DRY-RUN)")
+            print(f"  NEXO_HOME: {nexo_home}")
+            print(f"  snapshot:  {snapshot}")
+            if backup_target is not None:
+                print(f"  backup → {backup_target}")
+            if agents_to_restart:
+                print(f"  LaunchAgents to restart: {len(agents_to_restart)}")
+            print("  (no filesystem or launchctl changes were made)")
+        return 0
+
+    if not assume_yes:
+        if not (sys.stdin.isatty() and sys.stdout.isatty()):
+            print("ERROR: interactive confirmation required. Pass --yes to proceed non-interactively.", file=sys.stderr)
+            return 1
+        print("This will replace the current NEXO_HOME with the pre-F0.6 snapshot.")
+        print(f"  Current ~/.nexo → {backup_target if backup_target else '(nothing to back up, current missing)'}")
+        print(f"  Restored from snapshot → {nexo_home}")
+        if agents_to_restart:
+            print(f"  LaunchAgents affected: {len(agents_to_restart)}")
+        answer = input("Type 'ROLLBACK' to proceed: ").strip()
+        if answer != "ROLLBACK":
+            print("Aborted — exact token not typed.")
+            return 1
+
+    def _run_launchctl(cmd: list[str]) -> tuple[int, str]:
+        try:
+            proc = _subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+            return proc.returncode, (proc.stderr or "").strip()
+        except _subprocess.TimeoutExpired as exc:
+            return 124, f"timeout: {exc}"
+        except FileNotFoundError:
+            return 127, "launchctl not found"
+        except Exception as exc:  # noqa: BLE001  — launchctl errors are varied
+            return 1, str(exc)
+
+    executed: list[dict] = []
+
+    if agents_to_restart and not keep_agents:
+        for plist in agents_to_restart:
+            rc, err = _run_launchctl(["launchctl", "unload", str(plist)])
+            executed.append({"op": "unload", "plist": str(plist), "rc": rc, "err": err})
+
+    if backup_target is not None:
+        try:
+            nexo_home.rename(backup_target)
+            executed.append({"op": "rename_home", "to": str(backup_target), "rc": 0})
+        except OSError as exc:
+            executed.append({"op": "rename_home", "to": str(backup_target), "rc": 1, "err": str(exc)})
+            report["status"] = "error_rename_home"
+            report["executed"] = executed
+            if emit_json:
+                print(_json.dumps(report, indent=2))
+            else:
+                print(f"ERROR: failed to move {nexo_home} → {backup_target}: {exc}", file=sys.stderr)
+                print("       No changes to snapshot. Current NEXO_HOME is intact.", file=sys.stderr)
+            return 1
+
+    try:
+        snapshot.rename(nexo_home)
+        executed.append({"op": "rename_snapshot", "to": str(nexo_home), "rc": 0})
+    except OSError as exc:
+        executed.append({"op": "rename_snapshot", "to": str(nexo_home), "rc": 1, "err": str(exc)})
+        # Best-effort rollback of the backup rename so the user isn't left without NEXO_HOME.
+        if backup_target is not None and backup_target.exists() and not nexo_home.exists():
+            try:
+                backup_target.rename(nexo_home)
+                executed.append({"op": "rollback_rename_home", "rc": 0})
+            except OSError as rexc:
+                executed.append({"op": "rollback_rename_home", "rc": 1, "err": str(rexc)})
+        report["status"] = "error_rename_snapshot"
+        report["executed"] = executed
+        if emit_json:
+            print(_json.dumps(report, indent=2))
+        else:
+            print(f"ERROR: failed to move snapshot → NEXO_HOME: {exc}", file=sys.stderr)
+        return 1
+
+    if agents_to_restart and not keep_agents:
+        for plist in agents_to_restart:
+            if not plist.exists():
+                # The snapshot may not have the same plist set; skip silently.
+                executed.append({"op": "load_skip_missing", "plist": str(plist), "rc": 0})
+                continue
+            rc, err = _run_launchctl(["launchctl", "load", str(plist)])
+            executed.append({"op": "load", "plist": str(plist), "rc": rc, "err": err})
+
+    report["status"] = "done"
+    report["executed"] = executed
+    if backup_target is not None:
+        report["backup_target"] = str(backup_target)
+
+    if emit_json:
+        print(_json.dumps(report, indent=2))
+    else:
+        print("nexo rollback f06: done")
+        print(f"  restored:  {nexo_home}")
+        if backup_target is not None:
+            print(f"  prior home saved at: {backup_target}")
+            print(f"    review and rm -rf {backup_target}  when you are sure.")
+        if agents_to_restart:
+            print(f"  LaunchAgents reloaded: {len(agents_to_restart)}")
+    return 0
+
+
 def _update(args):
     """Update the installed runtime.
 
@@ -2699,6 +2892,37 @@ def main():
                                 help="Skip the interactive confirmation prompt")
     recover_parser.add_argument("--json", action="store_true", help="JSON output")
 
+    # -- rollback --
+    rollback_parser = sub.add_parser(
+        "rollback",
+        help="Reverse a structural migration using a pre-change snapshot",
+    )
+    rollback_sub = rollback_parser.add_subparsers(dest="rollback_command")
+    rollback_f06_p = rollback_sub.add_parser(
+        "f06",
+        help="Revert the F0.6 layout migration using ~/.nexo-pre-f06-snapshot",
+    )
+    rollback_f06_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would happen, do not mutate filesystem or LaunchAgents.",
+    )
+    rollback_f06_p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip the interactive confirmation prompt.",
+    )
+    rollback_f06_p.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit machine-readable JSON instead of text output.",
+    )
+    rollback_f06_p.add_argument(
+        "--keep-agents-running",
+        action="store_true",
+        help="Do not bootout / reload LaunchAgents. Advanced use; leaves stale services.",
+    )
+
     # -- clients --
     clients_parser = sub.add_parser("clients", help="Shared client config management")
     clients_sub = clients_parser.add_subparsers(dest="clients_command")
@@ -2998,6 +3222,11 @@ def main():
         return _update(args)
     elif args.command == "recover":
         return _recover(args)
+    elif args.command == "rollback":
+        if args.rollback_command == "f06":
+            return _rollback_f06(args)
+        rollback_parser.print_help()
+        return 0
     elif args.command == "clients":
         if args.clients_command == "sync":
             return _clients_sync(args)

package/src/core_schedule_controls.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import platform
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -209,6 +210,51 @@ def _save_core_schedule_overrides(overrides: dict[str, dict[str, Any]]) -> Path:
     return path
 
 
+def _audit_log_path() -> Path:
+    home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    # Prefer the F0.6 runtime/logs location with a legacy fallback so audit
+    # entries remain contiguous across installs that have not yet migrated.
+    new = home / "runtime" / "logs" / "core-schedule-overrides.log"
+    legacy = home / "logs" / "core-schedule-overrides.log"
+    if new.parent.is_dir() or not legacy.parent.is_dir():
+        return new
+    return legacy
+
+
+def _append_override_audit(
+    *,
+    name: str,
+    action: str,
+    previous: dict[str, Any],
+    current: dict[str, Any],
+    warning: str,
+    actor: str,
+) -> None:
+    """Append a single-line JSON audit record for a schedule override change.
+
+    Writes to ``~/.nexo/runtime/logs/core-schedule-overrides.log`` (or the
+    legacy location on pre-F0.6 installs). Best-effort only: a failed log
+    write never blocks the override itself.
+    """
+    try:
+        log_path = _audit_log_path()
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z"),
+            "name": name,
+            "action": action,
+            "previous": previous,
+            "current": current,
+            "warning": warning or "",
+            "actor": actor or "cli",
+        }
+        with log_path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception:
+        # Audit logging is best-effort — never fail the operator action.
+        pass
+
+
 def _apply_calendar_override(base_cron: dict[str, Any], start_hour: str) -> dict[str, Any]:
     parsed = _parse_daily_at(start_hour)
     schedule = base_cron.get("schedule")
@@ -417,6 +463,7 @@ def set_core_schedule(
     interval_seconds: int | None = None,
     daily_at: str | None = None,
     clear: bool = False,
+    actor: str = "cli",
 ) -> dict[str, Any]:
     clean_name = _normalize_name(name)
     if clean_name in _TOGGLEABLE_AUTOMATIONS:
@@ -437,6 +484,7 @@ def set_core_schedule(
         }
 
     overrides = load_core_schedule_overrides()
+    previous_snapshot = dict(overrides.get(clean_name) or {})
     changed = False
     warning = ""
     if clear:
@@ -482,6 +530,24 @@ def set_core_schedule(
         }
 
     config_path = _save_core_schedule_overrides(overrides)
+
+    if changed:
+        current_snapshot = dict(overrides.get(clean_name) or {})
+        if clear:
+            audit_action = "clear"
+        elif not previous_snapshot:
+            audit_action = "set"
+        else:
+            audit_action = "update"
+        _append_override_audit(
+            name=clean_name,
+            action=audit_action,
+            previous=previous_snapshot,
+            current=current_snapshot,
+            warning=warning,
+            actor=actor,
+        )
+
     sync_result = _sync_core_crons_runtime()
     refreshed = get_core_schedule_status(clean_name)
     refreshed.update({