nexo-brain 2.6.3 → 2.6.5

package/bin/nexo-brain.js

@@ -295,7 +295,7 @@ function getDefaultSchedule(timezone) {
     timezone: timezone || "UTC",
     auto_update: true,
     power_policy: "unset",
-    power_policy_version: 1,
+    power_policy_version: 2,
     processes: {
       "cognitive-decay": { hour: 3, minute: 0 },
       "postmortem": { hour: 23, minute: 30 },
@@ -315,14 +315,19 @@ async function maybeConfigurePowerPolicy(schedule, useDefaults) {
   }
   if (useDefaults || !process.stdin.isTTY || !process.stdout.isTTY) {
     schedule.power_policy = "unset";
-    schedule.power_policy_version = 1;
+    schedule.power_policy_version = 2;
     return schedule;
   }
 
   console.log("");
   log("Optional power policy:");
-  log("If enabled, NEXO will try to keep the machine awake for background work.");
-  const answer = (await ask("  Keep this machine awake for background work? [y/N/later]: ")).trim().toLowerCase();
+  log("If enabled, NEXO will activate a platform power helper for background work.");
+  if (process.platform === "darwin") {
+    log("On macOS this uses the native caffeinate helper. Closed-lid operation depends on your setup, so wake recovery remains active.");
+  } else if (process.platform === "linux") {
+    log("On Linux this uses systemd-inhibit or caffeine when available. Closed-lid behavior depends on host power settings.");
+  }
+  const answer = (await ask("  Enable the background power helper for this machine? [y/N/later]: ")).trim().toLowerCase();
   if (answer === "y" || answer === "yes") {
     schedule.power_policy = "always_on";
   } else if (answer === "later" || answer === "l") {
@@ -330,7 +335,7 @@ async function maybeConfigurePowerPolicy(schedule, useDefaults) {
   } else {
     schedule.power_policy = "disabled";
   }
-  schedule.power_policy_version = 1;
+  schedule.power_policy_version = 2;
   fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
   return schedule;
 }
@@ -1064,9 +1069,9 @@ async function main() {
       scanQ: "  Want me to analyze your environment to get to know you deeply?\n  Everything stays local, nothing leaves your machine.\n\n    1. Yes, analyze everything\n    2. No, I'll tell you over time\n  > ",
       scanStart: "Getting to know you... this takes 1-2 minutes.",
       scanDone: "Done.",
-      caffeinateQ: "  Keep Mac awake for my cognitive processes at night?\n  (I consolidate memory, clean duplicates, and discover connections while you sleep)\n    1. Yes\n    2. No\n  > ",
-      caffYes: "Nocturnal processes scheduled.",
-      caffNo: "Ok, I'll run them when I can.",
+      caffeinateQ: "  Enable the Mac power helper for my background processes?\n  (Uses caffeinate. Closed-lid operation depends on your setup; wake recovery stays active.)\n    1. Yes\n    2. No\n  > ",
+      caffYes: "Power helper enabled.",
+      caffNo: "Ok, wake recovery will cover missed windows.",
       dashboardQ: "  Enable web dashboard at localhost:6174?\n  (Always-on UI to explore memory, sessions, learnings, and system health)\n    1. Yes\n    2. No\n  > ",
       dashYes: "Dashboard enabled.",
       dashNo: "Dashboard disabled. You can start it manually: nexo dashboard",
@@ -1096,9 +1101,9 @@ async function main() {
       scanQ: "  ¿Quieres que analice tu entorno para conocerte a fondo?\n  Todo queda en local, nada sale de tu máquina.\n\n    1. Sí, analiza todo\n    2. No, ya te iré contando\n  > ",
       scanStart: "Conociéndote... esto toma 1-2 minutos.",
       scanDone: "Listo.",
-      caffeinateQ: "  ¿Mantengo el Mac despierto para mis procesos cognitivos nocturnos?\n  (Consolido memoria, limpio duplicados y descubro conexiones mientras duermes)\n    1. Sí\n    2. No\n  > ",
-      caffYes: "Procesos nocturnos programados.",
-      caffNo: "Ok, los ejecutaré cuando pueda.",
+      caffeinateQ: "  ¿Activo el helper de energía del Mac para mis procesos en segundo plano?\n  (Usa caffeinate. Con la tapa cerrada depende de tu setup; la recuperación al despertar sigue activa.)\n    1. Sí\n    2. No\n  > ",
+      caffYes: "Helper de energía activado.",
+      caffNo: "Ok, la recuperación al despertar cubrirá las ventanas perdidas.",
       dashboardQ: "  ¿Activar el dashboard web en localhost:6174?\n  (UI siempre activa para explorar memoria, sesiones, learnings y salud del sistema)\n    1. Sí\n    2. No\n  > ",
       dashYes: "Dashboard activado.",
       dashNo: "Dashboard desactivado. Puedes iniciarlo manualmente: nexo dashboard",
@@ -1128,9 +1133,9 @@ async function main() {
       scanQ: "  Veux-tu que j'analyse ton environnement pour te connaître en profondeur ?\n  Tout reste local.\n\n    1. Oui, analyse tout\n    2. Non, je te raconterai\n  > ",
       scanStart: "Je fais connaissance... ça prend 1-2 minutes.",
       scanDone: "Terminé.",
-      caffeinateQ: "  Garder le Mac éveillé pour mes processus nocturnes ?\n    1. Oui\n    2. Non\n  > ",
-      caffYes: "Processus nocturnes programmés.",
-      caffNo: "Ok, je les exécuterai quand possible.",
+      caffeinateQ: "  Activer l'aide énergie du Mac pour mes processus en arrière-plan ?\n  (Utilise caffeinate. Avec le capot fermé, cela dépend de votre configuration ; la reprise au réveil reste active.)\n    1. Oui\n    2. Non\n  > ",
+      caffYes: "Aide énergie activée.",
+      caffNo: "D'accord, la reprise au réveil couvrira les fenêtres manquées.",
       dashboardQ: "  Activer le dashboard web sur localhost:6174 ?\n  (UI toujours active pour explorer mémoire, sessions et santé du système)\n    1. Oui\n    2. Non\n  > ",
       dashYes: "Dashboard activé.",
       dashNo: "Dashboard désactivé. Démarrage manuel : nexo dashboard",
@@ -1160,9 +1165,9 @@ async function main() {
       scanQ: "  Soll ich deine Umgebung analysieren um dich kennenzulernen?\n  Alles bleibt lokal.\n\n    1. Ja, analysiere alles\n    2. Nein, ich erzähle dir mit der Zeit\n  > ",
       scanStart: "Lerne dich kennen... dauert 1-2 Minuten.",
       scanDone: "Fertig.",
-      caffeinateQ: "  Mac wach halten für nächtliche Prozesse?\n    1. Ja\n    2. Nein\n  > ",
-      caffYes: "Nachtprozesse geplant.",
-      caffNo: "Ok, führe sie aus wenn möglich.",
+      caffeinateQ: "  Den Mac-Energiehelfer für meine Hintergrundprozesse aktivieren?\n  (Nutzt caffeinate. Bei geschlossenem Deckel hängt das vom Setup ab; Wiederaufnahme beim Aufwachen bleibt aktiv.)\n    1. Ja\n    2. Nein\n  > ",
+      caffYes: "Energiehelfer aktiviert.",
+      caffNo: "Okay, die Wiederaufnahme beim Aufwachen deckt verpasste Fenster ab.",
       dashboardQ: "  Web-Dashboard auf localhost:6174 aktivieren?\n  (Immer aktive UI für Speicher, Sitzungen und Systemgesundheit)\n    1. Ja\n    2. Nein\n  > ",
       dashYes: "Dashboard aktiviert.",
       dashNo: "Dashboard deaktiviert. Manuell starten: nexo dashboard",
@@ -1192,9 +1197,9 @@ async function main() {
       scanQ: "  Vuoi che analizzi il tuo ambiente per conoscerti a fondo?\n  Tutto resta locale.\n\n    1. Sì, analizza tutto\n    2. No, ti racconterò col tempo\n  > ",
       scanStart: "Ti conosco... ci vogliono 1-2 minuti.",
       scanDone: "Fatto.",
-      caffeinateQ: "  Tenere il Mac sveglio per i processi notturni?\n    1. Sì\n    2. No\n  > ",
-      caffYes: "Processi notturni programmati.",
-      caffNo: "Ok, li eseguirò quando possibile.",
+      caffeinateQ: "  Attivare l'helper energetico del Mac per i processi in background?\n  (Usa caffeinate. Con il coperchio chiuso dipende dal setup; il recupero al risveglio resta attivo.)\n    1. Sì\n    2. No\n  > ",
+      caffYes: "Helper energetico attivato.",
+      caffNo: "Ok, il recupero al risveglio coprirà le finestre perse.",
       dashboardQ: "  Attivare la dashboard web su localhost:6174?\n  (UI sempre attiva per esplorare memoria, sessioni e salute del sistema)\n    1. Sì\n    2. No\n  > ",
       dashYes: "Dashboard attivata.",
       dashNo: "Dashboard disattivata. Avvio manuale: nexo dashboard",
@@ -1224,9 +1229,9 @@ async function main() {
       scanQ: "  Queres que analise o teu ambiente para te conhecer a fundo?\n  Tudo fica local.\n\n    1. Sim, analisa tudo\n    2. Não, vou-te contando\n  > ",
       scanStart: "A conhecer-te... demora 1-2 minutos.",
       scanDone: "Pronto.",
-      caffeinateQ: "  Manter o Mac acordado para processos noturnos?\n    1. Sim\n    2. Não\n  > ",
-      caffYes: "Processos noturnos agendados.",
-      caffNo: "Ok, executo quando possível.",
+      caffeinateQ: "  Ativar o helper de energia do Mac para processos em segundo plano?\n  (Usa caffeinate. Com a tampa fechada depende do teu setup; a recuperação ao despertar continua ativa.)\n    1. Sim\n    2. Não\n  > ",
+      caffYes: "Helper de energia ativado.",
+      caffNo: "Ok, a recuperação ao despertar cobrirá janelas perdidas.",
       dashboardQ: "  Ativar dashboard web em localhost:6174?\n  (UI sempre ativa para explorar memória, sessões e saúde do sistema)\n    1. Sim\n    2. Não\n  > ",
       dashYes: "Dashboard ativado.",
       dashNo: "Dashboard desativado. Iniciar manualmente: nexo dashboard",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.3",
+  "version": "2.6.5",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO — Cognitive co-operator for Claude Code. Memory, emotional intelligence, overnight learning (Deep Sleep), personal scripts registry, cron management, trust scoring, managed evolution, and adaptive calibration.",
+  "description": "NEXO — local cognitive runtime for Claude Code. Persistent memory, overnight learning, recovery-aware crons, personal scripts, doctor diagnostics, startup preflight, and optional power helper.",
   "bin": {
     "nexo-brain": "./bin/nexo-brain.js",
     "nexo": "./bin/nexo.js"

package/src/auto_update.py

@@ -1378,8 +1378,8 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME) -> tuple[bool, list[str]]:
                     "init_db = getattr(db, 'init_db', None); "
                     "init_db() if callable(init_db) else None; "
                     "import script_registry; "
-                    "sync_scripts = getattr(script_registry, 'sync_personal_scripts', None); "
-                    "sync_scripts() if callable(sync_scripts) else None"
+                    "reconcile_scripts = getattr(script_registry, 'reconcile_personal_scripts', None); "
+                    "reconcile_scripts(dry_run=False) if callable(reconcile_scripts) else None"
                 ),
             ],
             cwd=str(dest),
@@ -1521,6 +1521,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
         "claude_md_update": None,
         "migrations": [],
         "power_policy": None,
+        "power_message": None,
         "error": None,
     }
 
@@ -1529,6 +1530,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
     choice = ensure_power_policy_choice(interactive=interactive, reason=entrypoint)
     power_result = apply_power_policy(choice.get("policy"))
     result["power_policy"] = choice.get("policy") or get_power_policy()
+    result["power_message"] = power_result.get("message")
     if power_result.get("ok"):
         result["actions"].append(f"power:{power_result.get('action')}")
 
@@ -1536,7 +1538,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
     if src_dir is not None and repo_dir is not None:
         try:
             from db import init_db
-            from script_registry import sync_personal_scripts
+            from script_registry import reconcile_personal_scripts
 
             _run_db_migrations()
             result["migrations"] = run_file_migrations()
@@ -1546,7 +1548,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
             _ensure_runtime_cli_wrapper()
             _ensure_runtime_cli_in_shell()
             init_db()
-            sync_personal_scripts()
+            reconcile_personal_scripts(dry_run=False)
             result["actions"].append("db+personal-sync")
         except Exception as e:
             result["error"] = str(e)
@@ -1601,6 +1603,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
     result = auto_update_check()
     result["entrypoint"] = entrypoint
     result["power_policy"] = choice.get("policy") or get_power_policy()
+    result["power_message"] = power_result.get("message")
     if power_result.get("ok"):
         actions = result.setdefault("actions", [])
         actions.append(f"power:{power_result.get('action')}")

package/src/cli.py

@@ -451,7 +451,7 @@ def _update(args):
     - Packaged/runtime-only install: delegate to plugins.update handle_update()
     """
     from auto_update import manual_sync_update, _resolve_sync_source
-    from runtime_power import ensure_power_policy_choice, apply_power_policy
+    from runtime_power import ensure_power_policy_choice, apply_power_policy, format_power_policy_label
 
     interactive = sys.stdin.isatty() and sys.stdout.isatty()
 
@@ -478,11 +478,14 @@ def _update(args):
                 "message": result,
                 "power_policy": choice.get("policy"),
                 "power_action": power_result.get("action"),
+                "power_details": power_result.get("details"),
             }, indent=2, ensure_ascii=False))
         else:
             print(result)
             if choice.get("prompted"):
-                print(f"Power policy: {choice.get('policy')}")
+                print(f"Power policy: {format_power_policy_label(choice.get('policy'))}")
+            if power_result.get("message"):
+                print(f"Power helper: {power_result.get('message')}")
         return 0 if "UPDATE SUCCESSFUL" in result or "Already up to date" in result else 1
 
     choice = ensure_power_policy_choice(interactive=interactive, reason="update")
@@ -490,6 +493,9 @@ def _update(args):
     result = manual_sync_update(interactive=interactive, allow_source_pull=True)
     result["power_policy"] = choice.get("policy")
     result["power_action"] = power_result.get("action")
+    result["power_details"] = power_result.get("details")
+    if power_result.get("message"):
+        result["power_message"] = power_result.get("message")
     if args.json:
         print(json.dumps(result, indent=2, ensure_ascii=False))
     else:
@@ -502,7 +508,9 @@ def _update(args):
             if result.get("pulled_source"):
                 print("  Source repo: pulled latest fast-forward before sync")
             if choice.get("prompted"):
-                print(f"  Power policy: {choice.get('policy')}")
+                print(f"  Power policy: {format_power_policy_label(choice.get('policy'))}")
+            if power_result.get("message"):
+                print(f"  Power helper: {power_result.get('message')}")
         else:
             print(f"UPDATE FAILED: {result.get('error', 'sync failed')}", file=sys.stderr)
     return 0 if result.get("ok") else 1

package/src/cron_recovery.py

@@ -272,6 +272,48 @@ def latest_successful_runs(cron_ids: list[str], *, db_path: Path = DB_PATH) -> d
     return result
 
 
+def active_started_runs(cron_ids: list[str], *, db_path: Path = DB_PATH) -> dict[str, datetime]:
+    """Return currently open cron_runs keyed by cron_id.
+
+    A run is considered active if it has started but not yet recorded a final
+    exit/ended timestamp. Catchup uses this to avoid relaunching the same cron
+    window while another invocation is already in flight.
+    """
+    if not cron_ids or not db_path.is_file():
+        return {}
+    conn = None
+    try:
+        conn = sqlite3.connect(str(db_path), timeout=2)
+        conn.row_factory = sqlite3.Row
+        placeholders = ",".join("?" for _ in cron_ids)
+        rows = conn.execute(
+            f"""
+            SELECT c1.cron_id, c1.started_at
+            FROM cron_runs c1
+            JOIN (
+                SELECT cron_id, MAX(id) AS max_id
+                FROM cron_runs
+                WHERE cron_id IN ({placeholders})
+                  AND (exit_code IS NULL OR ended_at IS NULL)
+                GROUP BY cron_id
+            ) latest ON latest.max_id = c1.id
+            """,
+            tuple(cron_ids),
+        ).fetchall()
+    except Exception:
+        return {}
+    finally:
+        with contextlib.suppress(Exception):
+            conn.close()
+
+    result: dict[str, datetime] = {}
+    for row in rows:
+        parsed = _parse_timestamp(row["started_at"], assume_utc=True)
+        if parsed is not None:
+            result[row["cron_id"]] = parsed
+    return result
+
+
 def legacy_state_runs(*, state_file: Path = STATE_FILE) -> dict[str, datetime]:
     state = _load_json(state_file, {})
     if not isinstance(state, dict):
@@ -315,6 +357,7 @@ def catchup_candidates(now: datetime | None = None) -> list[dict]:
     crons = load_enabled_crons() + load_managed_personal_crons()
     contracts = {cron["id"]: recovery_contract(cron) for cron in crons if cron.get("id")}
     successes = latest_successful_runs(list(contracts), db_path=DB_PATH)
+    active_runs = active_started_runs(list(contracts), db_path=DB_PATH)
     legacy = legacy_state_runs(state_file=STATE_FILE)
     candidates: list[dict] = []
 
@@ -341,8 +384,10 @@ def catchup_candidates(now: datetime | None = None) -> list[dict]:
                 continue
             due_at = now - timedelta(seconds=interval_seconds)
         last_success = successes.get(cron_id) or legacy.get(cron_id)
+        active_started = active_runs.get(cron_id)
         age_seconds = max(int((now - due_at).total_seconds()), 0)
-        missed = last_success is None or last_success < due_at
+        is_inflight = active_started is not None and active_started >= due_at
+        missed = (last_success is None or last_success < due_at) and not is_inflight
         within_window = contract["max_catchup_age"] <= 0 or age_seconds <= contract["max_catchup_age"]
 
         candidates.append({
@@ -354,8 +399,10 @@ def catchup_candidates(now: datetime | None = None) -> list[dict]:
             "schedule": schedule,
             "last_due_at": due_at,
             "last_success_at": last_success,
+            "active_started_at": active_started,
             "age_seconds": age_seconds,
             "missed": missed,
+            "inflight": is_inflight,
             "within_window": within_window,
         })
 

package/src/hooks/caffeinate-guard.sh

@@ -2,7 +2,7 @@
 # NEXO Caffeinate Guard — keeps the Mac awake so nocturnal processes run on schedule.
 # Runs as a LaunchAgent with KeepAlive=true. If killed, launchd restarts it.
 #
-# Uses caffeinate -s (prevent system sleep) with -i (prevent idle sleep).
-# The Mac screen can turn off but the system stays awake.
+# Uses the native macOS caffeinate helper. Closed-lid behavior remains
+# best-effort and depends on the host setup.
 
-exec caffeinate -s -i -w $$
+exec /usr/bin/caffeinate -d -i -m -s /bin/bash -lc 'while :; do sleep 3600; done'

package/src/runtime_power.py

@@ -4,12 +4,20 @@ from __future__ import annotations
 Manages the optional "prevent sleep" helper as an explicit, persisted runtime
 preference. The policy is stored in config/schedule.json to avoid introducing a
 second user-facing config surface.
+
+Important semantic note:
+- ``always_on`` means "enable the platform power helper" for best-effort
+  background availability.
+- It does not replace wake recovery or catchup.
+- On laptops, especially with the lid closed, behavior remains platform and
+  setup dependent.
 """
 
 import json
 import os
 import platform
 import plistlib
+import shutil
 import subprocess
 from pathlib import Path
 
@@ -20,7 +28,7 @@ CONFIG_DIR = NEXO_HOME / "config"
 SCHEDULE_FILE = CONFIG_DIR / "schedule.json"
 POWER_POLICY_KEY = "power_policy"
 POWER_POLICY_VERSION_KEY = "power_policy_version"
-POWER_POLICY_VERSION = 1
+POWER_POLICY_VERSION = 2
 POWER_POLICY_ALWAYS_ON = "always_on"
 POWER_POLICY_DISABLED = "disabled"
 POWER_POLICY_UNSET = "unset"
@@ -31,6 +39,9 @@ VALID_POWER_POLICIES = {
 }
 LAUNCH_AGENTS_DIR = Path.home() / "Library" / "LaunchAgents"
 LINUX_SYSTEMD_USER_DIR = Path.home() / ".config" / "systemd" / "user"
+MACOS_CAFFEINATE_PATH = Path("/usr/bin/caffeinate")
+MACOS_CLOSED_LID_BEHAVIOR = "best_effort"
+LINUX_CLOSED_LID_BEHAVIOR = "host_policy"
 
 
 def _schedule_defaults() -> dict:
@@ -80,6 +91,90 @@ def normalize_power_policy(value: str | None) -> str:
     return POWER_POLICY_UNSET
 
 
+def _detect_linux_power_helper() -> tuple[str | None, str | None]:
+    if shutil.which("systemd-inhibit"):
+        return "systemd-inhibit", shutil.which("systemd-inhibit")
+    if shutil.which("caffeine"):
+        return "caffeine", shutil.which("caffeine")
+    return None, None
+
+
+def describe_power_policy(policy: str | None = None, *, system: str | None = None) -> dict:
+    policy = normalize_power_policy(policy or get_power_policy())
+    system = system or platform.system()
+    base = {
+        "policy": policy,
+        "platform": system,
+        "helper": None,
+        "helper_path": None,
+        "helper_available": False,
+        "closed_lid_behavior": "n/a",
+        "requires_wake_recovery": True,
+        "summary": "",
+        "prompt_note": "",
+    }
+
+    if policy != POWER_POLICY_ALWAYS_ON:
+        state = "disabled" if policy == POWER_POLICY_DISABLED else "unset"
+        base["summary"] = f"Power helper {state}."
+        base["prompt_note"] = "Wake recovery and catchup remain available."
+        return base
+
+    if system == "Darwin":
+        available = MACOS_CAFFEINATE_PATH.is_file()
+        base.update({
+            "helper": "caffeinate",
+            "helper_path": str(MACOS_CAFFEINATE_PATH),
+            "helper_available": available,
+            "closed_lid_behavior": MACOS_CLOSED_LID_BEHAVIOR,
+            "summary": (
+                "Enable the native macOS caffeinate helper for best-effort "
+                "background availability."
+            ),
+            "prompt_note": (
+                "macOS uses the native caffeinate helper. Closed-lid operation "
+                "depends on your hardware/setup, so wake recovery remains active."
+            ),
+        })
+        return base
+
+    if system == "Linux":
+        helper, helper_path = _detect_linux_power_helper()
+        base.update({
+            "helper": helper,
+            "helper_path": helper_path,
+            "helper_available": bool(helper_path),
+            "closed_lid_behavior": LINUX_CLOSED_LID_BEHAVIOR,
+            "summary": (
+                "Enable the Linux power helper for best-effort background "
+                "availability."
+            ),
+            "prompt_note": (
+                "Linux uses systemd-inhibit or caffeine when available. "
+                "Closed-lid behavior depends on host power settings, so wake "
+                "recovery remains active."
+            ),
+        })
+        return base
+
+    base.update({
+        "summary": f"No power helper integration is available on {system}.",
+        "prompt_note": "Wake recovery and catchup remain available.",
+    })
+    return base
+
+
+def format_power_policy_label(policy: str | None = None, *, system: str | None = None) -> str:
+    details = describe_power_policy(policy=policy, system=system)
+    policy = details["policy"]
+    if policy == POWER_POLICY_ALWAYS_ON and details["platform"] == "Darwin":
+        return "always_on (macOS caffeinate, closed-lid best effort)"
+    if policy == POWER_POLICY_ALWAYS_ON and details["platform"] == "Linux":
+        helper = details["helper"] or "power helper"
+        return f"always_on ({helper}, closed-lid depends on host policy)"
+    return policy
+
+
 def get_power_policy(schedule: dict | None = None) -> str:
     schedule = schedule or load_schedule_config()
     return normalize_power_policy(schedule.get(POWER_POLICY_KEY))
@@ -100,17 +195,20 @@ def set_power_policy(policy: str) -> dict:
 def prompt_for_power_policy(
     *,
     reason: str = "install",
+    system: str | None = None,
     input_fn=input,
     output_fn=print,
 ) -> str:
+    details = describe_power_policy(POWER_POLICY_ALWAYS_ON, system=system)
     prompt = (
-        "[NEXO] Keep this machine awake for background work? "
+        "[NEXO] Enable the background power helper for this machine? "
         "[y]es / [n]o / [l]ater: "
     )
     output_fn(
         "[NEXO] This controls the optional prevent-sleep helper. "
-        "It improves background availability but should remain opt-in."
+        "It improves background availability but remains opt-in."
     )
+    output_fn(f"[NEXO] {details['prompt_note']}")
     while True:
         answer = str(input_fn(prompt)).strip().lower()
         if answer in {"y", "yes"}:
@@ -134,7 +232,12 @@ def ensure_power_policy_choice(
     prompted = False
     if interactive and policy == POWER_POLICY_UNSET:
         prompted = True
-        policy = prompt_for_power_policy(reason=reason, input_fn=input_fn, output_fn=output_fn)
+        policy = prompt_for_power_policy(
+            reason=reason,
+            system=platform.system(),
+            input_fn=input_fn,
+            output_fn=output_fn,
+        )
         schedule[POWER_POLICY_KEY] = policy
         schedule[POWER_POLICY_VERSION_KEY] = POWER_POLICY_VERSION
         save_schedule_config(schedule)
@@ -199,25 +302,37 @@ def apply_power_policy(policy: str | None = None) -> dict:
     system = platform.system()
     logs_dir = NEXO_HOME / "logs"
     logs_dir.mkdir(parents=True, exist_ok=True)
+    details = describe_power_policy(policy=policy, system=system)
 
     if system == "Darwin":
-        return _apply_macos_power_policy(policy)
+        return _apply_macos_power_policy(policy, details=details)
     if system == "Linux":
-        return _apply_linux_power_policy(policy)
+        return _apply_linux_power_policy(policy, details=details)
     return {
         "ok": policy != POWER_POLICY_ALWAYS_ON,
         "policy": policy,
         "platform": system,
         "action": "unsupported",
         "message": f"Unsupported platform for prevent-sleep policy: {system}",
+        "details": details,
     }
 
 
-def _apply_macos_power_policy(policy: str) -> dict:
+def _apply_macos_power_policy(policy: str, *, details: dict | None = None) -> dict:
     plist_path, plist = _macos_prevent_sleep_plist()
     label = plist["Label"]
     uid = str(os.getuid())
     if policy == POWER_POLICY_ALWAYS_ON:
+        details = details or describe_power_policy(policy, system="Darwin")
+        if not details.get("helper_available"):
+            return {
+                "ok": False,
+                "policy": policy,
+                "platform": "Darwin",
+                "action": "missing-helper",
+                "message": f"Required helper not found: {details.get('helper_path') or 'caffeinate'}",
+                "details": details,
+            }
         LAUNCH_AGENTS_DIR.mkdir(parents=True, exist_ok=True)
         with plist_path.open("wb") as fh:
             plistlib.dump(plist, fh)
@@ -235,6 +350,7 @@ def _apply_macos_power_policy(policy: str) -> dict:
             "action": "enabled",
             "plist_path": str(plist_path),
             "message": "" if ok else (result.stderr.strip() or result.stdout.strip()),
+            "details": details,
         }
 
     subprocess.run(["launchctl", "bootout", f"gui/{uid}", str(plist_path)], capture_output=True)
@@ -247,12 +363,23 @@ def _apply_macos_power_policy(policy: str) -> dict:
         "platform": "Darwin",
         "action": "disabled" if policy == POWER_POLICY_DISABLED else "deferred",
         "plist_path": str(plist_path),
+        "details": details or describe_power_policy(policy, system="Darwin"),
     }
 
 
-def _apply_linux_power_policy(policy: str) -> dict:
+def _apply_linux_power_policy(policy: str, *, details: dict | None = None) -> dict:
     service_path, service_body = _linux_prevent_sleep_service()
     if policy == POWER_POLICY_ALWAYS_ON:
+        details = details or describe_power_policy(policy, system="Linux")
+        if not details.get("helper_available"):
+            return {
+                "ok": False,
+                "policy": policy,
+                "platform": "Linux",
+                "action": "missing-helper",
+                "message": "No Linux power helper found. Install systemd-inhibit or caffeine.",
+                "details": details,
+            }
         LINUX_SYSTEMD_USER_DIR.mkdir(parents=True, exist_ok=True)
         service_path.write_text(service_body)
         subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
@@ -269,6 +396,7 @@ def _apply_linux_power_policy(policy: str) -> dict:
             "action": "enabled",
             "service_path": str(service_path),
             "message": "" if ok else (result.stderr.strip() or result.stdout.strip()),
+            "details": details,
         }
 
     subprocess.run(["systemctl", "--user", "disable", "--now", "nexo-prevent-sleep.service"], capture_output=True)
@@ -281,4 +409,5 @@ def _apply_linux_power_policy(policy: str) -> dict:
         "platform": "Linux",
         "action": "disabled" if policy == POWER_POLICY_DISABLED else "deferred",
         "service_path": str(service_path),
+        "details": details or describe_power_policy(policy, system="Linux"),
     }

package/src/scripts/nexo-prevent-sleep.sh

@@ -1,14 +1,20 @@
 #!/bin/bash
 # NEXO Prevent Sleep — keeps the machine awake so nocturnal processes run.
 #
-# macOS: uses caffeinate -s -i (prevent system + idle sleep)
+# macOS: uses native /usr/bin/caffeinate for best-effort background availability
 # Linux: uses systemd-inhibit or caffeine if available, otherwise no-op
 #
 # Run as LaunchAgent (KeepAlive) or systemd service.
 
 case "$(uname -s)" in
     Darwin)
-        exec caffeinate -s -i -w $$
+        if [[ ! -x /usr/bin/caffeinate ]]; then
+            echo "[NEXO] /usr/bin/caffeinate not found. macOS power helper unavailable."
+            exit 1
+        fi
+        # Keep the helper alive as long as this service runs. On laptops with the
+        # lid closed, actual behavior still depends on hardware and OS policy.
+        exec /usr/bin/caffeinate -d -i -m -s /bin/bash -lc 'while :; do sleep 3600; done'
         ;;
     Linux)
         if command -v systemd-inhibit &>/dev/null; then