nexo-brain 7.23.1 → 7.23.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.23.0",
+  "version": "7.23.4",
   "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,13 @@
 
 [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.23.1` is the current packaged-runtime line. Express patch over v7.23.0 - headless automations no longer hang on silent Claude children, synthetic followup prompts no longer trigger session-end loops, and runtime backups self-prune under a hard cap before creating new large artifacts.
+Version `7.23.4` is the current packaged-runtime line. Patch over v7.23.3 - release tags now fail closed when npm publication fails and OpenClaw lockfile metadata stays synchronized with the release version.
+
+Previously in `7.23.3`: patch over v7.23.2 - Followup runner skips DONE terminal statuses so already-finished followups do not re-enter executable batches.
+
+Previously in `7.23.2`: patch over v7.23.1 - Desktop-facing version checks refresh stale latest-version cache entries so a just-published Brain update can still appear inside NEXO Desktop.
+
+Previously in `7.23.1`: express patch over v7.23.0 - headless automations no longer hang on silent Claude children, synthetic followup prompts no longer trigger session-end loops, and runtime backups self-prune under a hard cap before creating new large artifacts.
 
 Previously in `7.23.0`: minor release over v7.22.0 - pre-answer routing now consults continuity evidence before visible replies, Memory Observations queue processing converges through a bounded processor, and audits expose saved-but-not-used stores, automation drift, MCP live/catalog gaps, artifact location and transcript coverage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.23.1",
+  "version": "7.23.4",
   "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/scripts/sync_release_artifacts.py

@@ -12,6 +12,7 @@ ROOT_PACKAGE_JSON = ROOT / "package.json"
 CLAUDE_PLUGIN_JSON = ROOT / ".claude-plugin" / "plugin.json"
 CLAWHUB_SKILL_MD = ROOT / "clawhub-skill" / "SKILL.md"
 OPENCLAW_PACKAGE_JSON = ROOT / "openclaw-plugin" / "package.json"
+OPENCLAW_PACKAGE_LOCK = ROOT / "openclaw-plugin" / "package-lock.json"
 OPENCLAW_MCP_BRIDGE = ROOT / "openclaw-plugin" / "src" / "mcp-bridge.ts"
 
 
@@ -37,6 +38,30 @@ def sync_json_version(path: Path, expected_version: str, label: str) -> bool:
     return True
 
 
+def sync_openclaw_package_lock(path: Path, expected_version: str) -> bool:
+    payload = load_json(path)
+    changed = False
+
+    if payload.get("version") != expected_version:
+        payload["version"] = expected_version
+        changed = True
+
+    root_package = payload.get("packages", {}).get("")
+    if not isinstance(root_package, dict):
+        fail("OpenClaw package-lock.json is missing packages['']")
+
+    if root_package.get("version") != expected_version:
+        root_package["version"] = expected_version
+        changed = True
+
+    if not changed:
+        return False
+
+    dump_json(path, payload)
+    print(f"[sync-release-artifacts] synced OpenClaw package-lock -> {expected_version}")
+    return True
+
+
 def sync_clawhub_skill(skill_path: Path, expected_version: str) -> bool:
     text = skill_path.read_text()
     updated = text
@@ -99,6 +124,7 @@ def main() -> None:
         CLAUDE_PLUGIN_JSON: CLAUDE_PLUGIN_JSON.read_text(),
         CLAWHUB_SKILL_MD: CLAWHUB_SKILL_MD.read_text(),
         OPENCLAW_PACKAGE_JSON: OPENCLAW_PACKAGE_JSON.read_text(),
+        OPENCLAW_PACKAGE_LOCK: OPENCLAW_PACKAGE_LOCK.read_text(),
         OPENCLAW_MCP_BRIDGE: OPENCLAW_MCP_BRIDGE.read_text(),
     }
 
@@ -109,6 +135,8 @@ def main() -> None:
         changed.append("clawhub-skill/SKILL.md")
     if sync_json_version(OPENCLAW_PACKAGE_JSON, root_version, "OpenClaw package"):
         changed.append("openclaw-plugin/package.json")
+    if sync_openclaw_package_lock(OPENCLAW_PACKAGE_LOCK, root_version):
+        changed.append("openclaw-plugin/package-lock.json")
     if sync_openclaw_bridge(OPENCLAW_MCP_BRIDGE, root_version):
         changed.append("openclaw-plugin/src/mcp-bridge.ts")
 

package/src/auto_update.py

@@ -115,33 +115,16 @@ def _env_int(name: str, default: int) -> int:
         return default
 
 
-BACKUP_MAX_BYTES = _env_int("NEXO_BACKUP_MAX_BYTES", 50 * 1024 * 1024 * 1024)
-BACKUP_MIN_FREE_BYTES = _env_int("NEXO_BACKUP_MIN_FREE_BYTES", 5 * 1024 * 1024 * 1024)
+BACKUP_MAX_BYTES = paths.backup_retention_cap_bytes()
+BACKUP_MIN_FREE_BYTES = paths.backup_min_free_bytes()
 LOCAL_CONTEXT_MAX_BACKUP_BYTES = _env_int("NEXO_LOCAL_CONTEXT_MAX_BACKUP_BYTES", 2 * 1024 * 1024 * 1024)
 _LAST_BACKUP_ERROR = ""
 
 
 def _run_runtime_backup_prune() -> None:
-    script = SRC_DIR / "scripts" / "prune_runtime_backups.py"
-    if not script.is_file():
-        return
-    try:
-        subprocess.run(
-            [
-                sys.executable,
-                str(script),
-                "--root",
-                str(paths.backups_dir()),
-                "--apply",
-                "--max-bytes",
-                str(BACKUP_MAX_BYTES),
-            ],
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
-    except Exception as e:
-        _log(f"Backup self-clean warning: {e}")
+    result = paths.run_runtime_backup_prune(max_bytes=BACKUP_MAX_BYTES)
+    if result.get("ok") is False and not result.get("skipped"):
+        _log(f"Backup self-clean warning: {result.get('error') or result.get('stderr') or 'unknown'}")
 
 
 def _backup_free_bytes() -> int | None:
@@ -154,14 +137,7 @@ def _backup_free_bytes() -> int | None:
 
 
 def _backup_space_error() -> str | None:
-    _run_runtime_backup_prune()
-    free = _backup_free_bytes()
-    if free is not None and free < BACKUP_MIN_FREE_BYTES:
-        return (
-            "free disk below NEXO backup safety floor after automatic cleanup "
-            f"({free}B < {BACKUP_MIN_FREE_BYTES}B)"
-        )
-    return None
+    return paths.backup_space_error(reason="auto_update")
 
 
 def _should_include_local_context_backup(path: Path) -> bool:
@@ -283,15 +259,15 @@ def _cleanup_legacy_root_db_stubs(runtime_root: Path = NEXO_HOME, *, dry_run: bo
             continue
 
         if backup_root is None:
-            timestamp = time.strftime("%Y-%m-%d-%H%M%S", time.gmtime())
-            backup_root = paths.backups_dir() / f"legacy-root-db-stubs-{timestamp}"
-            backup_root.mkdir(parents=True, exist_ok=True)
+            backup_root = paths.create_backup_dir("legacy-root-db-stubs")
         target = backup_root / candidate.name
         try:
             shutil.move(str(candidate), str(target))
             report["archived"].append({"path": str(candidate), "backup_path": str(target)})
         except Exception as exc:
             report["errors"].append({"path": str(candidate), "error": str(exc)})
+    if backup_root is not None:
+        paths.finalize_backup_snapshot(backup_root)
     return report
 
 
@@ -374,9 +350,7 @@ def _cleanup_empty_personal_brain_db_stubs(runtime_root: Path = NEXO_HOME, *, dr
             continue
 
         if backup_root is None:
-            timestamp = time.strftime("%Y-%m-%d-%H%M%S", time.gmtime())
-            backup_root = paths.backups_dir() / f"legacy-personal-brain-db-stubs-{timestamp}"
-            backup_root.mkdir(parents=True, exist_ok=True)
+            backup_root = paths.create_backup_dir("legacy-personal-brain-db-stubs")
         target = backup_root / candidate.name
         try:
             shutil.move(str(candidate), str(target))
@@ -387,6 +361,8 @@ def _cleanup_empty_personal_brain_db_stubs(runtime_root: Path = NEXO_HOME, *, dr
             })
         except Exception as exc:
             report["errors"].append({"path": str(candidate), "error": str(exc)})
+    if backup_root is not None:
+        paths.finalize_backup_snapshot(backup_root)
     return report
 
 
@@ -1613,7 +1589,7 @@ def _self_heal_if_wiped() -> dict | None:
         return report
 
     # Snapshot the current (wiped) state so the heal is reversible.
-    pre_heal_dir = paths.backups_dir() / f"pre-heal-{time.strftime('%Y-%m-%d-%H%M%S')}"
+    pre_heal_dir = paths.create_backup_dir("pre-heal")
     try:
         import shutil as _shutil
         pre_heal_dir.mkdir(parents=True, exist_ok=True)
@@ -1623,6 +1599,7 @@ def _self_heal_if_wiped() -> dict | None:
                 _shutil.copy2(str(sidecar), str(pre_heal_dir / sidecar.name))
     except Exception as e:
         _log(f"self-heal: pre-heal snapshot warning: {e}")
+    paths.finalize_backup_snapshot(pre_heal_dir)
 
     # Clear stale WAL/SHM before the restore so the new DB starts clean.
     for suffix in ("-wal", "-shm"):
@@ -2141,8 +2118,7 @@ def _backup_dbs() -> str | None:
     # path selection and turn into empty shells in the backup, breaking both
     # validation and rollback paths. Safe no-op when there are none.
     _purge_zero_byte_db_files()
-    timestamp = _time.strftime("%Y-%m-%d-%H%M%S")
-    backup_dir = paths.backups_dir() / f"pre-autoupdate-{timestamp}"
+    backup_dir: Path | None = None
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
     local_context_db = paths.memory_dir() / "local-context.db"
@@ -2162,7 +2138,7 @@ def _backup_dbs() -> str | None:
         _log(f"DB backup aborted: {space_err}")
         return None
 
-    backup_dir.mkdir(parents=True, exist_ok=True)
+    backup_dir = paths.create_backup_dir("pre-autoupdate")
     for db_file in db_files:
         src_conn = None
         dst_conn = None
@@ -2187,6 +2163,7 @@ def _backup_dbs() -> str | None:
         _rotate_auto_update_backups("pre-autoupdate-")
     except Exception as e:
         _log(f"Backup rotation warning (pre-autoupdate): {e}")
+    paths.finalize_backup_snapshot(backup_dir)
     return str(backup_dir)
 
 
@@ -2665,8 +2642,7 @@ def _promote_packaged_runtime_code_to_core() -> None:
     def _conflict_dir() -> Path:
         nonlocal conflict_root
         if conflict_root is None:
-            conflict_root = paths.backups_dir() / f"packaged-code-f06-conflicts-{timestamp}"
-            conflict_root.mkdir(parents=True, exist_ok=True)
+            conflict_root = paths.create_backup_dir("packaged-code-f06-conflicts")
         return conflict_root
 
     def _same_file(a: Path, b: Path) -> bool:
@@ -2765,6 +2741,8 @@ def _promote_packaged_runtime_code_to_core() -> None:
             shutil.move(str(source), str(canonical))
         except Exception as exc:
             _log(f"[F0.6 packaged-code] move {source} -> {canonical} failed: {exc}")
+    if conflict_root is not None:
+        paths.finalize_backup_snapshot(conflict_root)
 
 
 def _ensure_f06_legacy_shims() -> None:
@@ -2783,8 +2761,7 @@ def _ensure_f06_legacy_shims() -> None:
     def _conflict_dir() -> Path:
         nonlocal conflict_root
         if conflict_root is None:
-            conflict_root = paths.backups_dir() / f"legacy-shim-conflicts-{timestamp}"
-            conflict_root.mkdir(parents=True, exist_ok=True)
+            conflict_root = paths.create_backup_dir("legacy-shim-conflicts")
         return conflict_root
 
     def _same_file(a: Path, b: Path) -> bool:
@@ -2950,6 +2927,8 @@ def _ensure_f06_legacy_shims() -> None:
         marker.write_text("F0.6\n", encoding="utf-8")
     except Exception:
         pass
+    if conflict_root is not None:
+        paths.finalize_backup_snapshot(conflict_root)
 
 
 def _rewrite_f06_launch_agents() -> int:
@@ -4430,9 +4409,7 @@ def _installed_scripts_classification(dest: Path) -> dict[str, str]:
 
 
 def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
-    timestamp = time.strftime("%Y-%m-%d-%H%M%S")
-    backup_dir = paths.backups_dir() / f"runtime-tree-{timestamp}"
-    backup_dir.mkdir(parents=True, exist_ok=True)
+    backup_dir = paths.create_backup_dir("runtime-tree")
 
     code_dirs = [
         "hooks",
@@ -4471,6 +4448,7 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
         _rotate_auto_update_backups("runtime-tree-")
     except Exception as e:
         _log(f"Backup rotation warning (runtime-tree): {e}")
+    paths.finalize_backup_snapshot(backup_dir)
     return str(backup_dir)
 
 

package/src/automation_reconciler.py

@@ -0,0 +1,383 @@
+"""Safe reconciliation plan/apply contract for NEXO automations.
+
+The reconciler never touches LaunchAgents and never deletes spool files. It
+only closes retryable stale cron rows and archives terminal spool records when
+the dry-run plan proves the action is deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import sqlite3
+from typing import Any, Mapping
+
+from automation_supervisor import (
+    AutomationSupervisorConfig,
+    audit_automation,
+    default_config as supervisor_default_config,
+    load_job_contracts,
+    _is_retryable,
+    _normalise_now,
+    _spool_cron_id,
+)
+
+
+DEFAULT_SPOOL_STALE_SECONDS = 60 * 60
+TERMINAL_SPOOL_STATUSES = {"done", "completed", "failed", "cancelled", "terminal"}
+
+
+@dataclass(frozen=True)
+class AutomationReconcileConfig:
+    nexo_db_path: Path | None = None
+    manifest_path: Path | None = None
+    cron_spool_dir: Path | None = None
+    cron_spool_archive_dir: Path | None = None
+    now: datetime | None = None
+    spool_stale_seconds: int = DEFAULT_SPOOL_STALE_SECONDS
+
+
+def default_config() -> AutomationReconcileConfig:
+    cfg = supervisor_default_config()
+    archive = cfg.cron_spool_dir / "archive" if cfg.cron_spool_dir else None
+    return AutomationReconcileConfig(
+        nexo_db_path=cfg.nexo_db_path,
+        manifest_path=cfg.manifest_path,
+        cron_spool_dir=cfg.cron_spool_dir,
+        cron_spool_archive_dir=archive,
+    )
+
+
+def build_reconciliation_plan(config: AutomationReconcileConfig | None = None) -> dict[str, Any]:
+    cfg = config or default_config()
+    now = _normalise_now(cfg.now)
+    supervisor_cfg = AutomationSupervisorConfig(
+        nexo_db_path=cfg.nexo_db_path,
+        manifest_path=cfg.manifest_path,
+        cron_spool_dir=cfg.cron_spool_dir,
+        now=now,
+    )
+    report = audit_automation(supervisor_cfg)
+    contracts, _excluded = load_job_contracts(cfg.manifest_path)
+    actions: list[dict[str, Any]] = []
+
+    for row in report.get("open_runs") or []:
+        status = str(row.get("status") or "")
+        run_id = row.get("run_id")
+        cron_id = str(row.get("cron_id") or "")
+        if status == "retryable" and run_id is not None:
+            actions.append(
+                {
+                    "action": "close_cron_run",
+                    "safe_apply": True,
+                    "run_id": run_id,
+                    "cron_id": cron_id,
+                    "started_at": str(row.get("started_at") or ""),
+                    "classification": status,
+                    "reason": row.get("reason", ""),
+                    "then": "scheduler may retry according to recovery_policy",
+                }
+            )
+        elif status in {"stuck", "abandoned"}:
+            actions.append(
+                {
+                    "action": "manual_review_open_run",
+                    "safe_apply": False,
+                    "run_id": run_id,
+                    "cron_id": cron_id,
+                    "classification": status,
+                    "reason": row.get("reason", ""),
+                }
+            )
+
+    spool_items = _classify_spool_items(
+        cfg.cron_spool_dir,
+        contracts=contracts,
+        now=now,
+        stale_seconds=cfg.spool_stale_seconds,
+    )
+    for item in spool_items:
+        if item["classification"] == "terminal":
+            actions.append(
+                {
+                    "action": "archive_spool_file",
+                    "safe_apply": True,
+                    "cron_id": item["cron_id"],
+                    "path": item["path"],
+                    "content_hash": item.get("content_hash", ""),
+                    "classification": "terminal",
+                    "reason": item["reason"],
+                }
+            )
+        elif item["classification"] in {"orphaned", "stale", "retryable"}:
+            actions.append(
+                {
+                    "action": "manual_review_spool_file",
+                    "safe_apply": False,
+                    "cron_id": item["cron_id"],
+                    "path": item["path"],
+                    "classification": item["classification"],
+                    "reason": item["reason"],
+                }
+            )
+
+    return {
+        "ok": True,
+        "generated_at": now.isoformat(),
+        "dry_run": True,
+        "actions": actions,
+        "spool_items": spool_items,
+        "summary": {
+            "actions": len(actions),
+            "safe_actions": sum(1 for item in actions if item.get("safe_apply")),
+            "manual_actions": sum(1 for item in actions if not item.get("safe_apply")),
+            "spool_items": len(spool_items),
+        },
+    }
+
+
+def apply_reconciliation_plan(plan: Mapping[str, Any], config: AutomationReconcileConfig | None = None) -> dict[str, Any]:
+    cfg = config or default_config()
+    now = _normalise_now(cfg.now)
+    applied: list[dict[str, Any]] = []
+    skipped: list[dict[str, Any]] = []
+    for action in plan.get("actions") or []:
+        if not isinstance(action, Mapping) or not action.get("safe_apply"):
+            skipped.append({"action": dict(action) if isinstance(action, Mapping) else action, "reason": "not_safe_apply"})
+            continue
+        kind = str(action.get("action") or "")
+        if kind == "close_cron_run":
+            applied.append(_close_cron_run(cfg, action, now=now))
+        elif kind == "archive_spool_file":
+            applied.append(_archive_spool_file(cfg, action, now=now))
+        else:
+            skipped.append({"action": dict(action), "reason": "unknown_safe_action"})
+    ok = not any(item.get("ok") is False for item in applied)
+    return {
+        "ok": ok,
+        "applied": applied,
+        "skipped": skipped,
+        "summary": {
+            "applied": len(applied),
+            "skipped": len(skipped),
+            "errors": sum(1 for item in applied if item.get("ok") is False),
+        },
+    }
+
+
+def _classify_spool_items(
+    spool_dir: Path | None,
+    *,
+    contracts: Mapping[str, Any],
+    now: datetime,
+    stale_seconds: int,
+) -> list[dict[str, Any]]:
+    if spool_dir is None or not spool_dir.exists():
+        return []
+    result: list[dict[str, Any]] = []
+    for path in sorted(spool_dir.glob("*.json")):
+        if not path.is_file():
+            continue
+        payload = _load_json(path)
+        cron_id = _spool_cron_id(path, contracts)
+        contract = contracts.get(cron_id)
+        mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc)
+        age_seconds = int((now - mtime).total_seconds())
+        status = str(payload.get("status") or "").strip().lower() if isinstance(payload, dict) else ""
+        terminal = bool(isinstance(payload, dict) and payload.get("terminal") is True) or status in TERMINAL_SPOOL_STATUSES
+        if contract is None:
+            classification = "orphaned"
+            reason = "spool item does not match a declared non-Evolution cron"
+        elif terminal:
+            classification = "terminal"
+            reason = "spool item is marked terminal and can be archived"
+        elif age_seconds > max(1, int(stale_seconds or DEFAULT_SPOOL_STALE_SECONDS)):
+            if _is_retryable(contract):
+                classification = "retryable"
+                reason = "stale spool item belongs to a retryable/idempotent cron"
+            else:
+                classification = "stale"
+                reason = "stale spool item has no retry contract"
+        else:
+            classification = "pending"
+            reason = "spool item is recent and pending normal processing"
+        result.append(
+            {
+                "cron_id": cron_id,
+                "path": str(path),
+                "age_seconds": max(age_seconds, 0),
+                "classification": classification,
+                "reason": reason,
+                "content_hash": _file_sha256(path),
+            }
+        )
+    return result
+
+
+def _close_cron_run(cfg: AutomationReconcileConfig, action: Mapping[str, Any], *, now: datetime) -> dict[str, Any]:
+    db_path = cfg.nexo_db_path
+    if db_path is None or not db_path.is_file():
+        return {"ok": False, "action": "close_cron_run", "error": "db_missing"}
+    run_id = action.get("run_id")
+    try:
+        run_id_int = int(run_id)
+    except Exception:
+        return {"ok": False, "action": "close_cron_run", "error": "invalid_run_id", "run_id": run_id}
+    current = _current_open_run(cfg, run_id_int)
+    expected_cron_id = str(action.get("cron_id") or "")
+    expected_classification = str(action.get("classification") or "")
+    expected_started_at = str(action.get("started_at") or "")
+    if not expected_cron_id or not expected_classification or not expected_started_at:
+        return {
+            "ok": False,
+            "action": "close_cron_run",
+            "error": "missing_plan_evidence",
+            "run_id": run_id_int,
+        }
+    if not current:
+        return {"ok": False, "action": "close_cron_run", "error": "stale_plan_run_not_open", "run_id": run_id_int}
+    if (
+        str(current.get("cron_id") or "") != expected_cron_id
+        or str(current.get("status") or "") != expected_classification
+        or str(current.get("started_at") or "") != expected_started_at
+        or expected_classification != "retryable"
+    ):
+        return {
+            "ok": False,
+            "action": "close_cron_run",
+            "error": "stale_plan_run_changed",
+            "run_id": run_id_int,
+            "expected_cron_id": expected_cron_id,
+            "current_cron_id": current.get("cron_id", ""),
+            "current_status": current.get("status", ""),
+            "current_started_at": current.get("started_at", ""),
+        }
+    conn = sqlite3.connect(str(db_path), timeout=5)
+    try:
+        cursor = conn.execute(
+            """
+            UPDATE cron_runs
+            SET ended_at = ?, exit_code = COALESCE(exit_code, 75),
+                summary = CASE WHEN COALESCE(summary, '') = '' THEN ? ELSE summary END,
+                error = CASE WHEN COALESCE(error, '') = '' THEN ? ELSE error END
+            WHERE id = ? AND cron_id = ? AND started_at = ? AND (ended_at IS NULL OR exit_code IS NULL)
+            """,
+            (
+                now.replace(microsecond=0).isoformat(),
+                "closed by automation reconciler",
+                str(action.get("reason") or "stale retryable run"),
+                run_id_int,
+                expected_cron_id,
+                expected_started_at,
+            ),
+        )
+        conn.commit()
+        return {"ok": True, "action": "close_cron_run", "run_id": run_id_int, "rows": cursor.rowcount}
+    finally:
+        conn.close()
+
+
+def _archive_spool_file(
+    cfg: AutomationReconcileConfig,
+    action: Mapping[str, Any],
+    *,
+    now: datetime,
+) -> dict[str, Any]:
+    spool_dir = cfg.cron_spool_dir
+    archive_dir = cfg.cron_spool_archive_dir or (spool_dir / "archive" if spool_dir else None)
+    if spool_dir is None or archive_dir is None:
+        return {"ok": False, "action": "archive_spool_file", "error": "spool_missing"}
+    source = Path(str(action.get("path") or ""))
+    try:
+        source_resolved = source.resolve(strict=True)
+        spool_resolved = spool_dir.resolve(strict=True)
+        source_resolved.relative_to(spool_resolved)
+    except Exception:
+        return {"ok": False, "action": "archive_spool_file", "error": "unsafe_path", "path": str(source)}
+    current = _current_spool_item(cfg, source_resolved, now=now)
+    expected_hash = str(action.get("content_hash") or "").strip()
+    if not expected_hash:
+        return {
+            "ok": False,
+            "action": "archive_spool_file",
+            "error": "missing_plan_evidence",
+            "path": str(source),
+        }
+    if (
+        not current
+        or current.get("classification") != "terminal"
+        or current.get("cron_id") != str(action.get("cron_id") or "")
+        or current.get("content_hash") != expected_hash
+    ):
+        return {
+            "ok": False,
+            "action": "archive_spool_file",
+            "error": "stale_plan_spool_changed",
+            "path": str(source),
+            "current": current or {},
+        }
+    dated_dir = archive_dir / now.strftime("%Y%m%d")
+    dated_dir.mkdir(parents=True, exist_ok=True)
+    target = dated_dir / source.name
+    if target.exists():
+        target = dated_dir / f"{source.stem}-{int(now.timestamp())}{source.suffix}"
+    shutil.move(str(source_resolved), str(target))
+    return {"ok": True, "action": "archive_spool_file", "from": str(source), "to": str(target)}
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _current_open_run(cfg: AutomationReconcileConfig, run_id: int) -> dict[str, Any] | None:
+    supervisor_cfg = AutomationSupervisorConfig(
+        nexo_db_path=cfg.nexo_db_path,
+        manifest_path=cfg.manifest_path,
+        cron_spool_dir=cfg.cron_spool_dir,
+        now=_normalise_now(cfg.now),
+    )
+    report = audit_automation(supervisor_cfg)
+    for row in report.get("open_runs") or []:
+        try:
+            if int(row.get("run_id")) == run_id:
+                return dict(row)
+        except Exception:
+            continue
+    return None
+
+
+def _current_spool_item(
+    cfg: AutomationReconcileConfig,
+    source_resolved: Path,
+    *,
+    now: datetime,
+) -> dict[str, Any] | None:
+    contracts, _excluded = load_job_contracts(cfg.manifest_path)
+    items = _classify_spool_items(
+        cfg.cron_spool_dir,
+        contracts=contracts,
+        now=now,
+        stale_seconds=cfg.spool_stale_seconds,
+    )
+    for item in items:
+        try:
+            if Path(str(item.get("path") or "")).resolve(strict=True) == source_resolved:
+                return dict(item)
+        except Exception:
+            continue
+    return None
+
+
+def _file_sha256(path: Path) -> str:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except Exception:
+        return ""