nexo-brain 5.3.28 → 5.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.28",
+  "version": "5.4.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 `5.3.11` is the current packaged-runtime line: protocol and Cortex now reject malformed `outcome`, `task_type`, and `impact_level` values explicitly instead of silently coercing them into other valid states, so task history, debt, hot context, and decision telemetry stay trustworthy even when a caller passes a bad contract payload.
+Version `5.4.0` is the current packaged-runtime line: runtime event bus at `~/.nexo/runtime/events.ndjson`, `nexo notify` for one-shot proactive events, `nexo health --json` for a rolled-up subsystem snapshot, `nexo logs --tail --json` for structured log access, and a safe flat→nested migration for `calibration.json` on older installs.
+
+Previously in `5.3.30`: four read-only CLI commands (`nexo schema`, `nexo identity`, `nexo onboard`, `nexo scan-profile`) let external UIs auto-adapt to the editable schema, identity, onboarding wizard, and profile heuristics.
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
@@ -488,7 +490,9 @@ NEXO Brain doesn't just respond — it runs 13 core recovery-aware background jo
 | **followup-hygiene** | Weekly (Sun) | Normalizes statuses, flags stale followups, cleans orphans |
 | **learning-housekeep** | 03:15 daily | Dedup learnings, adjust weights by usage, process overdue reviews, reconcile decision outcomes |
 | **immune** | Every 30 min | Quarantine processing, memory promotion/rejection, synaptic pruning |
+| **impact-scorer** | 05:45 daily | Scores active followups so queues can prioritize by expected impact |
 | **synthesis** | 06:00 daily | Memory synthesis — discovers cross-memory patterns |
+| **outcome-checker** | 08:00 daily | Verifies tracked outcomes and marks them met, pending, or missed |
 | **watchdog** | Every 30 min | Monitors services, LaunchAgents, and infrastructure health |
 | **auto-close-sessions** | Every 5 min | Cleans stale sessions |
 

package/bin/nexo-brain.js

@@ -88,6 +88,20 @@ function log(msg) {
   console.log(`  ${msg}`);
 }
 
+function duplicateArtifactCanonicalName(name) {
+  const ext = path.extname(name);
+  const stem = ext ? name.slice(0, -ext.length) : name;
+  const match = stem.match(/^(.*) ([2-9]\d*)$/);
+  if (!match) return null;
+  return `${match[1]}${ext}`;
+}
+
+function isDuplicateArtifactName(name, dirPath = "") {
+  const canonical = duplicateArtifactCanonicalName(name);
+  if (!canonical || !dirPath) return false;
+  return fs.existsSync(path.join(dirPath, canonical));
+}
+
 function syncWatchdogHashRegistry(nexoHome) {
   try {
     const watchdogPath = path.join(nexoHome, "scripts", "nexo-watchdog.sh");
@@ -122,7 +136,7 @@ function writeRuntimeCoreArtifactsManifest(nexoHome, srcDir) {
       return fs.readdirSync(dirPath)
         .filter((name) => {
           const full = path.join(dirPath, name);
-          return fs.existsSync(full) && fs.statSync(full).isFile();
+          return fs.existsSync(full) && fs.statSync(full).isFile() && !isDuplicateArtifactName(name, dirPath);
         })
         .sort();
     };
@@ -192,6 +206,7 @@ function getCoreRuntimeFlatFiles(srcDir = path.join(__dirname, "..", "src")) {
   const discoveredRootModules = fs.existsSync(srcDir)
     ? fs.readdirSync(srcDir)
       .filter((name) => {
+        if (isDuplicateArtifactName(name, srcDir)) return false;
         const stat = fs.statSync(path.join(srcDir, name));
         if (!stat.isFile()) return false;
         // Include Python modules and any flat JSON config the Python runtime
@@ -1551,7 +1566,7 @@ async function main() {
         const copyDirRec = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
           fs.readdirSync(src).forEach(item => {
-            if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db")) return;
+            if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db") || isDuplicateArtifactName(item, src)) return;
             const srcPath = path.join(src, item);
             const destPath = path.join(dest, item);
             if (fs.statSync(srcPath).isDirectory()) {
@@ -1620,7 +1635,7 @@ async function main() {
         const pluginsDest = path.join(NEXO_HOME, "plugins");
         fs.mkdirSync(pluginsDest, { recursive: true });
         if (fs.existsSync(pluginsSrc)) {
-          fs.readdirSync(pluginsSrc).filter(f => f.endsWith(".py")).forEach((f) => {
+          fs.readdirSync(pluginsSrc).filter(f => f.endsWith(".py") && !isDuplicateArtifactName(f, pluginsSrc)).forEach((f) => {
             fs.copyFileSync(path.join(pluginsSrc, f), path.join(pluginsDest, f));
           });
         }
@@ -1772,7 +1787,7 @@ async function main() {
         const copyDirRec2 = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
           fs.readdirSync(src).forEach(item => {
-            if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db")) return;
+            if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db") || isDuplicateArtifactName(item, src)) return;
             const srcP = path.join(src, item);
             const destP = path.join(dest, item);
             if (fs.statSync(srcP).isDirectory()) copyDirRec2(srcP, destP);
@@ -1806,7 +1821,7 @@ async function main() {
         const copyDirRec3 = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
           fs.readdirSync(src).forEach(item => {
-            if (item === "__pycache__" || item.endsWith(".pyc")) return;
+            if (item === "__pycache__" || item.endsWith(".pyc") || isDuplicateArtifactName(item, src)) return;
             const srcP = path.join(src, item);
             const destP = path.join(dest, item);
             if (fs.statSync(srcP).isDirectory()) copyDirRec3(srcP, destP);
@@ -1831,6 +1846,7 @@ async function main() {
       if (fs.existsSync(templatesSrc)) {
         fs.mkdirSync(templatesDest, { recursive: true });
         for (const f of fs.readdirSync(templatesSrc)) {
+          if (isDuplicateArtifactName(f, templatesSrc)) continue;
           const src = path.join(templatesSrc, f);
           const dest = path.join(templatesDest, f);
           if (fs.statSync(src).isFile()) {
@@ -1838,6 +1854,7 @@ async function main() {
           } else if (fs.statSync(src).isDirectory()) {
             fs.mkdirSync(dest, { recursive: true });
             for (const sf of fs.readdirSync(src)) {
+              if (isDuplicateArtifactName(sf, src)) continue;
               const ssrc = path.join(src, sf);
               if (fs.statSync(ssrc).isFile()) {
                 fs.copyFileSync(ssrc, path.join(dest, sf));
@@ -2354,7 +2371,7 @@ async function main() {
   const copyDirRecursive = (src, dest) => {
     fs.mkdirSync(dest, { recursive: true });
     fs.readdirSync(src).forEach(item => {
-      if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db")) return;
+      if (item === "__pycache__" || item.endsWith(".pyc") || item.endsWith(".db") || isDuplicateArtifactName(item, src)) return;
       const srcPath = path.join(src, item);
       const destPath = path.join(dest, item);
       if (fs.statSync(srcPath).isDirectory()) {
@@ -2461,7 +2478,7 @@ async function main() {
   // Plugins (all .py files in plugins/)
   fs.mkdirSync(path.join(NEXO_HOME, "plugins"), { recursive: true });
   if (fs.existsSync(pluginsSrcDir)) {
-    fs.readdirSync(pluginsSrcDir).filter(f => f.endsWith(".py")).forEach((f) => {
+    fs.readdirSync(pluginsSrcDir).filter(f => f.endsWith(".py") && !isDuplicateArtifactName(f, pluginsSrcDir)).forEach((f) => {
       fs.copyFileSync(path.join(pluginsSrcDir, f), path.join(NEXO_HOME, "plugins", f));
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.28",
+  "version": "5.4.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.",
   "homepage": "https://nexo-brain.com",

package/src/auto_update.py

@@ -18,6 +18,7 @@ import time
 from pathlib import Path
 
 from runtime_home import export_resolved_nexo_home, managed_nexo_home
+from tree_hygiene import is_duplicate_artifact_name
 
 NEXO_HOME = export_resolved_nexo_home()
 DATA_DIR = NEXO_HOME / "data"
@@ -63,6 +64,20 @@ def _log(msg: str):
     print(f"[NEXO auto-update] {msg}", file=sys.stderr)
 
 
+def _runtime_copy_ignore(*extra_patterns: str):
+    base_ignore = shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo", "*.db", *extra_patterns)
+
+    def _ignore(dir_name: str, names: list[str]) -> set[str]:
+        ignored = set(base_ignore(dir_name, names))
+        ignored.update(
+            name for name in names
+            if is_duplicate_artifact_name(Path(dir_name) / name)
+        )
+        return ignored
+
+    return _ignore
+
+
 def _critical_table_count(db_path: Path, table: str) -> int | None:
     """Return COUNT(*) for a critical table when it exists, otherwise None."""
     import sqlite3
@@ -470,7 +485,7 @@ def _refresh_installed_manifest():
         if src_crons.exists():
             dst_crons.mkdir(parents=True, exist_ok=True)
             for f in src_crons.iterdir():
-                if f.is_file():
+                if f.is_file() and not is_duplicate_artifact_name(f):
                     shutil.copy2(str(f), str(dst_crons / f.name))
             _log("Refreshed installed crons manifest")
     except Exception as e:
@@ -746,7 +761,7 @@ def _sync_hooks():
     hooks_dest.mkdir(parents=True, exist_ok=True)
     synced = 0
     for f in hooks_src.iterdir():
-        if f.is_file() and f.suffix == ".sh":
+        if f.is_file() and f.suffix == ".sh" and not is_duplicate_artifact_name(f):
             dest = hooks_dest / f.name
             shutil.copy2(str(f), str(dest))
             os.chmod(str(dest), 0o755)
@@ -1441,7 +1456,7 @@ def _auto_update_check_locked() -> dict:
             import shutil
             scripts_dest.mkdir(parents=True, exist_ok=True)
             for f in scripts_src.iterdir():
-                if f.name.startswith('.') or f.name == '__pycache__':
+                if f.name.startswith('.') or f.name == '__pycache__' or is_duplicate_artifact_name(f):
                     continue
                 dest = scripts_dest / f.name
                 if f.is_file() and not dest.exists():
@@ -1475,12 +1490,12 @@ def _auto_update_check_locked() -> dict:
         if doctor_src.is_dir():
             import shutil
             if not doctor_dest.is_dir():
-                shutil.copytree(str(doctor_src), str(doctor_dest), ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+                shutil.copytree(str(doctor_src), str(doctor_dest), ignore=_runtime_copy_ignore())
                 _log("Backfilled doctor package")
             else:
                 # Update existing files
                 for root, dirs, files in os.walk(str(doctor_src)):
-                    dirs[:] = [d for d in dirs if d != "__pycache__"]
+                    dirs[:] = [d for d in dirs if d != "__pycache__" and not is_duplicate_artifact_name(Path(root) / d)]
                     rel = os.path.relpath(root, str(doctor_src))
                     dest_dir = doctor_dest / rel
                     dest_dir.mkdir(parents=True, exist_ok=True)
@@ -1488,6 +1503,8 @@ def _auto_update_check_locked() -> dict:
                         if f.endswith(".pyc"):
                             continue
                         src_f = Path(root) / f
+                        if is_duplicate_artifact_name(src_f):
+                            continue
                         dst_f = dest_dir / f
                         if not dst_f.exists() or src_f.stat().st_mtime > dst_f.stat().st_mtime:
                             shutil.copy2(str(src_f), str(dst_f))
@@ -1501,11 +1518,11 @@ def _auto_update_check_locked() -> dict:
         if skills_src.is_dir():
             import shutil
             if not skills_dest.is_dir():
-                shutil.copytree(str(skills_src), str(skills_dest), ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+                shutil.copytree(str(skills_src), str(skills_dest), ignore=_runtime_copy_ignore())
                 _log("Backfilled skills-core")
             else:
                 for root, dirs, files in os.walk(str(skills_src)):
-                    dirs[:] = [d for d in dirs if d != "__pycache__"]
+                    dirs[:] = [d for d in dirs if d != "__pycache__" and not is_duplicate_artifact_name(Path(root) / d)]
                     rel = os.path.relpath(root, str(skills_src))
                     dest_dir = skills_dest / rel
                     dest_dir.mkdir(parents=True, exist_ok=True)
@@ -1513,6 +1530,8 @@ def _auto_update_check_locked() -> dict:
                         if f.endswith(".pyc"):
                             continue
                         src_f = Path(root) / f
+                        if is_duplicate_artifact_name(src_f):
+                            continue
                         dst_f = dest_dir / f
                         if not dst_f.exists() or src_f.stat().st_mtime > dst_f.stat().st_mtime:
                             shutil.copy2(str(src_f), str(dst_f))
@@ -1539,7 +1558,7 @@ def _auto_update_check_locked() -> dict:
         import shutil
         if templates_src.is_dir():
             for item in templates_src.iterdir():
-                if item.name == "__pycache__":
+                if item.name == "__pycache__" or is_duplicate_artifact_name(item):
                     continue
                 dest_item = templates_dest / item.name
                 if item.is_file():
@@ -1548,7 +1567,7 @@ def _auto_update_check_locked() -> dict:
                 elif item.is_dir():
                     dest_item.mkdir(parents=True, exist_ok=True)
                     for sub in item.iterdir():
-                        if sub.is_file():
+                        if sub.is_file() and not is_duplicate_artifact_name(sub):
                             dest_sub = dest_item / sub.name
                             if not dest_sub.exists() or sub.stat().st_mtime > dest_sub.stat().st_mtime:
                                 shutil.copy2(str(sub), str(dest_sub))
@@ -1735,6 +1754,8 @@ def _discover_runtime_root_python_modules(base_dir: Path) -> list[str]:
             continue
         if item.name.startswith(".") or item.name == "__init__.py":
             continue
+        if is_duplicate_artifact_name(item):
+            continue
         modules.append(item.name)
     return modules
 
@@ -1857,7 +1878,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
             shutil.copytree(
                 str(pkg_src),
                 str(pkg_dest),
-                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo", "*.db"),
+                ignore=_runtime_copy_ignore(),
             )
             copied_packages += 1
 
@@ -1874,7 +1895,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     if plugins_src.is_dir():
         plugins_dest.mkdir(parents=True, exist_ok=True)
         for item in plugins_src.iterdir():
-            if item.is_file() and item.suffix == ".py":
+            if item.is_file() and item.suffix == ".py" and not is_duplicate_artifact_name(item):
                 shutil.copy2(str(item), str(plugins_dest / item.name))
 
     _emit_progress(progress_fn, "Copying scripts...")
@@ -1883,13 +1904,13 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     if scripts_src.is_dir():
         scripts_dest.mkdir(parents=True, exist_ok=True)
         for item in scripts_src.iterdir():
-            if item.name == "__pycache__" or item.name.startswith("."):
+            if item.name == "__pycache__" or item.name.startswith(".") or is_duplicate_artifact_name(item):
                 continue
             dst = scripts_dest / item.name
             if item.is_dir():
                 if dst.exists():
                     shutil.rmtree(str(dst), ignore_errors=True)
-                shutil.copytree(str(item), str(dst), ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+                shutil.copytree(str(item), str(dst), ignore=_runtime_copy_ignore())
             elif item.is_file():
                 existing_class = installed_script_classes.get(item.name, "")
                 if dst.exists() and existing_class in {"personal", "non-script"}:
@@ -1919,7 +1940,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     if templates_src.is_dir():
         templates_dest.mkdir(parents=True, exist_ok=True)
         for item in templates_src.iterdir():
-            if item.name == "__pycache__":
+            if item.name == "__pycache__" or is_duplicate_artifact_name(item):
                 continue
             if item.is_file():
                 shutil.copy2(str(item), str(templates_dest / item.name))
@@ -1927,7 +1948,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
                 sub_dest = templates_dest / item.name
                 sub_dest.mkdir(parents=True, exist_ok=True)
                 for sub in item.iterdir():
-                    if sub.is_file():
+                    if sub.is_file() and not is_duplicate_artifact_name(sub):
                         shutil.copy2(str(sub), str(sub_dest / sub.name))
 
     package_json = repo_dir / "package.json"
@@ -1948,7 +1969,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     if skills_src.is_dir():
         if skills_dest.exists():
             shutil.rmtree(str(skills_dest), ignore_errors=True)
-        shutil.copytree(str(skills_src), str(skills_dest), ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+        shutil.copytree(str(skills_src), str(skills_dest), ignore=_runtime_copy_ignore())
 
     bin_dir = dest / "bin"
     bin_dir.mkdir(parents=True, exist_ok=True)

package/src/calibration_migration.py

@@ -0,0 +1,242 @@
+"""Calibration migration — flat → nested schema for calibration.json.
+
+Older NEXO installations wrote calibration.json with flat top-level keys
+(user_name, autonomy, role…). The canonical shape is nested
+(user.name, personality.autonomy, meta.role). This module detects the
+flat shape and migrates to nested with a backup.
+
+Design:
+  - Backup lives at calibration.json.pre-migrate-<version>
+  - Unknown fields are preserved verbatim under `legacy_unmapped`
+  - Revert is just: cp backup → calibration.json
+  - Idempotent: if already nested, returns OK without touching the file
+
+No network, no DB. Pure file I/O so it can run from any runtime.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+
+FLAT_TO_NESTED = {
+    # user.*
+    "user_name": ("user", "name"),
+    "name": ("user", "name"),
+    "language": ("user", "language"),
+    "lang": ("user", "language"),
+    "timezone": ("user", "timezone"),
+    "tz": ("user", "timezone"),
+    "assistant_name": ("user", "assistant_name"),
+    # personality.*
+    "autonomy": ("personality", "autonomy"),
+    "communication": ("personality", "communication"),
+    "honesty": ("personality", "honesty"),
+    "proactivity": ("personality", "proactivity"),
+    "error_handling": ("personality", "error_handling"),
+    # preferences.*
+    "menu_on_demand": ("preferences", "menu_on_demand"),
+    "show_pending_items": ("preferences", "show_pending_items"),
+    "execution_first": ("preferences", "execution_first"),
+    "report_style": ("preferences", "report_style"),
+    # meta.*
+    "role": ("meta", "role"),
+    "technical_level": ("meta", "technical_level"),
+}
+
+# Keys that always live at the top level regardless of shape
+TOP_LEVEL_KEYS = {"version", "created", "mood_history", "operator_name"}
+
+
+def _calibration_path(nexo_home: Path | None = None) -> Path:
+    home = nexo_home or Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    return home / "brain" / "calibration.json"
+
+
+def _is_nested(cal: dict) -> bool:
+    """Nested shape has at least one of {user, personality, preferences, meta} as dict."""
+    for key in ("user", "personality", "preferences", "meta"):
+        if isinstance(cal.get(key), dict):
+            return True
+    return False
+
+
+def _has_flat_markers(cal: dict) -> bool:
+    """Flat shape has top-level keys that normally belong inside nested groups."""
+    for flat_key in FLAT_TO_NESTED:
+        if flat_key in cal:
+            return True
+    return False
+
+
+def detect(cal: dict | None = None, *, path: Path | None = None) -> dict:
+    """Return {'shape': 'nested'|'flat'|'mixed'|'empty', 'reason': str}."""
+    if cal is None:
+        target = path or _calibration_path()
+        if not target.is_file():
+            return {"shape": "empty", "reason": "file does not exist"}
+        try:
+            cal = json.loads(target.read_text())
+        except Exception as exc:
+            return {"shape": "empty", "reason": f"unreadable: {exc}"}
+    if not isinstance(cal, dict) or not cal:
+        return {"shape": "empty", "reason": "empty or not an object"}
+
+    nested = _is_nested(cal)
+    flat = _has_flat_markers(cal)
+    if nested and flat:
+        return {"shape": "mixed", "reason": "both nested groups and flat keys present"}
+    if nested:
+        return {"shape": "nested", "reason": "already canonical"}
+    if flat:
+        return {"shape": "flat", "reason": "top-level flat keys, no nested groups"}
+    return {"shape": "empty", "reason": "no recognizable keys"}
+
+
+def migrate(
+    cal: dict,
+    *,
+    preserve_unmapped: bool = True,
+) -> dict:
+    """Convert a flat calibration payload to nested. Returns a new dict."""
+    if _is_nested(cal) and not _has_flat_markers(cal):
+        return dict(cal)
+
+    result: dict[str, Any] = {}
+    legacy_unmapped: dict[str, Any] = {}
+
+    # Preserve nested groups already present
+    for group in ("user", "personality", "preferences", "meta"):
+        if isinstance(cal.get(group), dict):
+            result[group] = dict(cal[group])
+
+    # Preserve top-level metadata
+    for key in TOP_LEVEL_KEYS:
+        if key in cal:
+            result[key] = cal[key]
+
+    # Walk flat keys
+    for key, value in cal.items():
+        if key in ("user", "personality", "preferences", "meta"):
+            continue
+        if key in TOP_LEVEL_KEYS:
+            continue
+        if key in FLAT_TO_NESTED:
+            group, leaf = FLAT_TO_NESTED[key]
+            result.setdefault(group, {})
+            # Nested value wins over flat if both exist
+            if leaf not in result[group]:
+                result[group][leaf] = value
+        else:
+            legacy_unmapped[key] = value
+
+    if legacy_unmapped and preserve_unmapped:
+        result["legacy_unmapped"] = legacy_unmapped
+
+    # Bump version marker if present
+    if "version" not in result:
+        result["version"] = 1
+
+    return result
+
+
+def backup_path(path: Path, version: str = "5.4.0") -> Path:
+    return path.with_name(path.name + f".pre-migrate-{version}")
+
+
+def apply_migration(
+    path: Path | None = None,
+    *,
+    version: str = "5.4.0",
+    dry_run: bool = False,
+) -> dict:
+    """Migrate calibration.json on disk. Returns a status dict."""
+    target = path or _calibration_path()
+    if not target.is_file():
+        return {"status": "skipped", "reason": "calibration.json not found", "path": str(target)}
+
+    try:
+        original = json.loads(target.read_text())
+    except Exception as exc:
+        return {"status": "error", "reason": f"unreadable: {exc}", "path": str(target)}
+
+    shape = detect(original)
+    if shape["shape"] in ("nested", "empty"):
+        return {
+            "status": "noop",
+            "reason": f"already {shape['shape']}",
+            "path": str(target),
+            "shape": shape["shape"],
+        }
+
+    migrated = migrate(original)
+    if dry_run:
+        return {
+            "status": "preview",
+            "reason": "dry run",
+            "path": str(target),
+            "shape": shape["shape"],
+            "original": original,
+            "migrated": migrated,
+            "backup_would_be": str(backup_path(target, version)),
+        }
+
+    backup = backup_path(target, version)
+    try:
+        shutil.copy2(target, backup)
+    except Exception as exc:
+        return {"status": "error", "reason": f"backup failed: {exc}", "path": str(target)}
+
+    try:
+        target.write_text(json.dumps(migrated, ensure_ascii=False, indent=2))
+    except Exception as exc:
+        # Attempt revert
+        try:
+            shutil.copy2(backup, target)
+        except Exception:
+            pass
+        return {"status": "error", "reason": f"write failed: {exc}", "path": str(target)}
+
+    # Re-detect to confirm
+    post = detect(migrated)
+    if post["shape"] != "nested":
+        # Revert
+        try:
+            shutil.copy2(backup, target)
+        except Exception:
+            pass
+        return {
+            "status": "error",
+            "reason": f"post-migration shape is {post['shape']}",
+            "path": str(target),
+        }
+
+    return {
+        "status": "migrated",
+        "reason": "flat → nested",
+        "path": str(target),
+        "backup": str(backup),
+        "shape": post["shape"],
+        "migrated_at": time.time(),
+    }
+
+
+def revert(
+    path: Path | None = None,
+    *,
+    version: str = "5.4.0",
+) -> dict:
+    """Revert calibration.json to the most recent pre-migrate backup."""
+    target = path or _calibration_path()
+    backup = backup_path(target, version)
+    if not backup.is_file():
+        return {"status": "error", "reason": f"no backup found at {backup}", "path": str(target)}
+    try:
+        shutil.copy2(backup, target)
+    except Exception as exc:
+        return {"status": "error", "reason": f"copy failed: {exc}", "path": str(target)}
+    return {"status": "reverted", "from": str(backup), "path": str(target)}