nexo-brain 2.6.4 → 2.6.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.3",
-  "description": "Cognitive co-operator — persistent memory, learning, autonomous processes, Deep Sleep overnight analysis, unified diagnostics, executable skills, day orchestrator, and web dashboard for AI agents.",
+  "version": "2.6.6",
+  "description": "Local cognitive runtime for Claude Code — persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",
     "email": "info@nexo-brain.com",

package/README.md

@@ -6,7 +6,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-> The first AI memory system with architectural inhibitory control — the agent reasons about whether to act before acting. Cognitive Cortex, Context Continuity via auto-compaction hooks, Smart Startup, Context Packets, Auto-Prime, 30 Core Rules as DNA, auto-update, auto-diary, CLAUDE.md version tracker, personal scripts registry, and Claude Code plugin structure. Battle-tested from 6 months of production use, validated via multi-AI debate.
+> Local cognitive runtime for Claude Code — persistent memory, overnight learning, runtime CLI, recovery-aware background jobs, startup preflight, and doctor diagnostics. 150+ MCP tools. Benchmarked on LoCoMo (F1 0.588, +55% vs GPT-4). Submitted to the Claude Code plugin marketplace.
 
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 
@@ -198,7 +198,7 @@ This means long sessions (8+ hours) feel like one continuous conversation instea
 
 ## Cognitive Features
 
-NEXO Brain provides **144+ MCP tools** across 20+ categories. These features implement cognitive science concepts that go beyond basic memory:
+NEXO Brain provides **150+ MCP tools** across 20+ categories. These features implement cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 
@@ -269,7 +269,7 @@ Full results in [`benchmarks/locomo/results/`](benchmarks/locomo/results/).
 
 ## Nervous System (v2.0.0)
 
-NEXO Brain doesn't just respond — it runs 14 autonomous processes in the background, like a biological nervous system. They handle maintenance, health monitoring, and self-improvement without any user interaction:
+NEXO Brain doesn't just respond — it runs 13 core recovery-aware background jobs plus optional helpers, like a biological nervous system. They handle maintenance, health monitoring, and self-improvement without any user interaction:
 
 | Script | Schedule | What It Does |
 |--------|----------|-------------|
@@ -280,7 +280,7 @@ NEXO Brain doesn't just respond — it runs 14 autonomous processes in the backg
 | **postmortem** | 23:30 daily | Session consolidation, extract patterns from day's events |
 | **catchup** | On boot | Runs any missed scheduled processes (Mac was off/asleep) |
 | **tcc-approve** | On boot (macOS) | Auto-approve macOS permissions for Claude Code updates |
-| **prevent-sleep** | Optional opt-in daemon | Keeps machine awake for nocturnal processes when `power_policy=always_on` (caffeinate/systemd-inhibit) |
+| **prevent-sleep** | Always (daemon) | Keeps machine awake for nocturnal processes (caffeinate/systemd-inhibit) |
 | **evolution** | Weekly (Sun) | Self-improvement proposals — NEXO suggests and applies enhancements |
 | **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 |
@@ -289,7 +289,7 @@ NEXO Brain doesn't just respond — it runs 14 autonomous processes in the backg
 | **watchdog** | Every 30 min | Monitors services, LaunchAgents, and infrastructure health |
 | **auto-close-sessions** | Every 5 min | Cleans stale sessions |
 
-Core processes are defined in `src/crons/manifest.json` and auto-synced to your system by `nexo_update`. On macOS they run via LaunchAgents; on Linux via systemd user timers. `tcc-approve`, `prevent-sleep`, and `backup` are platform/personal helpers — not in the manifest but listed above for completeness. `prevent-sleep` is opt-in via the persisted power policy (`always_on` / `disabled` / `unset`). Personal scripts (your own automations) are tracked separately in the Personal Scripts Registry, can declare their own recovery policy inline, and are never touched by the core sync. If your Mac was asleep during a scheduled process, the catch-up system can now recover both core crons and managed personal schedules according to their recovery contract.
+Core processes are defined in `src/crons/manifest.json` and auto-synced to your system by `nexo_update`. On macOS they run via LaunchAgents; on Linux via systemd user timers. `tcc-approve`, `prevent-sleep`, and `backup` are platform/personal helpers — not in the manifest but listed above for completeness. Personal crons (your own scripts) are never touched by the sync. If your Mac was asleep during a scheduled process, the catch-up script re-runs everything in order when it wakes.
 
 ## Deep Sleep v2 — Overnight Learning (v2.1.0)
 
@@ -390,7 +390,7 @@ This opens `localhost:6174` in your browser. Add `--port 8080` to change the por
 
 ## Full Orchestration System
 
-Memory alone doesn't make a co-operator. What makes the difference is the **behavioral loop** — the automated discipline that ensures every session starts informed, runs with guardrails, and ends with self-reflection. The hooks and lifecycle below are built into the core product. The optional Day Orchestrator (autonomous headless cycles) was removed from core in v2.6.0 — power users can set it up as a personal script.
+Memory alone doesn't make a co-operator. What makes the difference is the **behavioral loop** — the automated discipline that ensures every session starts informed, runs with guardrails, and ends with self-reflection.
 
 ### Automated Hooks
 
@@ -452,6 +452,57 @@ npx nexo-brain  # detects current version, migrates automatically
 - **Never touches your data** (memories, learnings, preferences)
 - Saves updated CLAUDE.md as reference (doesn't overwrite customizations)
 
+## Runtime CLI (v2.6.0)
+
+NEXO Brain includes a local CLI that runs independently of Claude Code:
+
+- `nexo chat` — launch Claude Code with NEXO as the operator
+- `nexo update` — sync runtime from source, run migrations, reconcile schedules
+- `nexo doctor --tier runtime` — boot/runtime/deep diagnostics with `--fix` mode
+- `nexo scripts list` — list all personal scripts and their status
+- `nexo scripts reconcile` — align declared schedules with actual LaunchAgents/systemd
+- `nexo -v` — show installed runtime version
+
+The CLI lives at `NEXO_HOME/bin/nexo` and is added to your PATH during install.
+
+## Personal Scripts Registry (v2.6.0)
+
+Scripts in `NEXO_HOME/scripts/` are first-class managed entities:
+
+- Tracked in SQLite with metadata, categories, and schedule associations
+- Inline metadata in scripts declares name, runtime, schedule, and recovery policy
+- `nexo scripts create NAME` scaffolds a new script with the correct template
+- `nexo scripts reconcile` creates/repairs LaunchAgents from declared metadata
+- `nexo scripts sync` discovers filesystem state and updates the registry
+- `nexo doctor --tier runtime` detects orphaned schedules, missing plists, and drift
+
+Personal scripts are completely separate from core NEXO processes. The `crons/manifest.json` defines core; everything in `NEXO_HOME/scripts/` is personal.
+
+## Recovery-Aware Background Jobs (v2.6.2)
+
+Core and personal jobs now declare explicit recovery contracts in `crons/manifest.json`:
+
+| Field | Purpose |
+|-------|---------|
+| `recovery_policy` | `catchup`, `restart`, or `skip` |
+| `run_on_boot` | Re-run when the machine starts |
+| `run_on_wake` | Re-run after sleep/resume |
+| `idempotent` | Safe to re-run without side effects |
+| `max_catchup_age` | Maximum age of a missed window to still catch up |
+
+If the Mac was asleep during a scheduled window, `catchup` detects the gap from `cron_runs` (not a state file) and re-executes eligible jobs once. Interval-based personal scripts get a single recovery run, not repeated ticks.
+
+## Startup Preflight (v2.6.2)
+
+Before `nexo chat` or MCP server start, NEXO runs a preflight check:
+
+1. Apply power policy (caffeinate on macOS, systemd-inhibit on Linux)
+2. Run safe local migrations and backfills
+3. Sync personal scripts registry
+4. For dev-linked runtimes: check if source repo is behind, pull if safe, sync to runtime
+
+This replaces the old "blind startup" where NEXO entered without verifying runtime health.
+
 ## Knowledge Graph (v0.8)
 
 A bi-temporal entity-relationship graph with 988 nodes and 896 edges. Entities and relationships carry both valid-time (when the fact was true) and system-time (when it was recorded), enabling temporal queries like "what did we know about X last Tuesday?". BFS traversal discovers multi-hop connections between concepts. Event-sourced edges with smart dedup (ADD/UPDATE/NOOP) prevent redundant writes while preserving full history.
@@ -501,7 +552,7 @@ The installer handles everything:
     - Node.js project detected
   Configuring MCP server...
   Setting up nervous system...
-    14 autonomous processes configured.
+    13 core recovery-aware jobs configured.
     Dashboard configured at localhost:6174.
   Caffeinate enabled.
   Generating operator instructions...
@@ -513,50 +564,46 @@ The installer handles everything:
 
 ### Starting a Session
 
-The installer creates a shell alias with your chosen name. Just type it:
+After install, use the runtime CLI:
 
 ```bash
-atlas
+nexo chat          # Launch Claude Code with NEXO as operator
+nexo doctor        # Check runtime health
+nexo update        # Pull latest version and sync
+nexo scripts list  # See your personal scripts
 ```
 
-Under the hood, the alias runs:
-```bash
-claude --dangerously-skip-permissions "."
-```
-`--dangerously-skip-permissions` launches Claude Code with tool-use permissions pre-approved so the operator can act autonomously. The `"."` triggers the operator to start immediately. Operator behavior (startup, context, greeting) is defined in `~/.claude/CLAUDE.md`.
+Or use the shell alias created during install (e.g. `atlas`), which runs `claude --dangerously-skip-permissions "."` — launching Claude Code with tool-use permissions pre-approved so the operator can act autonomously.
 
-That's it. No need to run `claude` manually. Your operator will greet you immediately — adapted to the time of day, resuming from where you left off if there's a previous session. No cold starts, no waiting for your input.
+Your operator will greet you immediately — adapted to the time of day, resuming from where you left off. No cold starts.
 
 ### What Gets Installed
 
 | Component | What | Where |
 |-----------|------|-------|
 | Cognitive engine | Python: fastembed, numpy, vector search | pip packages |
-| MCP server | 144+ tools for memory, cognition, learning, guard | NEXO_HOME/ |
+| MCP server | 150+ tools for memory, cognition, learning, guard | NEXO_HOME/ |
+| Claude Code Plugin | Submitted to the Claude Code plugin marketplace (Anthropic) | `.claude-plugin/` |
 | Plugins | Guard, episodic memory, cognitive memory, entities, preferences, update, etc. | Code: src/plugins/, Personal: NEXO_HOME/plugins/ |
 | Hooks (7) | SessionStart, Stop, PostToolUse, PreCompact, PostCompact | NEXO_HOME/hooks/ |
-| Nervous system | 14 autonomous processes (decay, sleep, audit, evolution, watchdog, dashboard, etc.) | NEXO_HOME/scripts/ |
+| Nervous system | 13 core recovery-aware jobs + optional helpers (dashboard, prevent-sleep) | NEXO_HOME/scripts/ |
 | Dashboard | Web UI at localhost:6174 (23 modules, dark theme) — opt-in, always-on | NEXO_HOME/dashboard/ |
-| Runtime CLI | `nexo` command: chat, scripts, doctor, skills, update | NEXO_HOME/bin/ |
+| Runtime CLI | `nexo` command: scripts, doctor, skills, update | NEXO_HOME/bin/ |
 | Doctor | Unified diagnostics: boot/runtime/deep tiers, `--fix` mode | src/doctor/ |
 | Skills v2 | Executable skills with guide/execute/hybrid modes, approval levels | NEXO_HOME/skills/ |
-| Personal Scripts Registry | User-defined scripts tracked in SQLite with scheduling, reconciliation, and 9 MCP tools | NEXO_HOME/scripts/ |
+| Startup Preflight | Health checks before every `nexo chat` or server start | Built into CLI |
 | CLAUDE.md | Complete operator instructions (Codex, hooks, guard, trust, memory) | ~/.claude/CLAUDE.md |
 | Schedule config | schedule.json with customizable process times and timezone | NEXO_HOME/config/ |
 | Auto-update | Non-blocking startup check (5s max), opt-out via schedule.json | Built into server startup |
 | CLAUDE.md tracker | Version-tracked core sections with safe updates preserving customizations | Built into auto-update |
 | Auto-diary | 3-layer system: PostToolUse every 10 calls, PreCompact emergency, heartbeat DIARY_OVERDUE | Built into hooks |
-| Claude Code config | MCP server + 7 hooks + core processes registered | ~/.claude/settings.json |
+| Claude Code config | MCP server + 7 hooks + 15 processes registered | ~/.claude/settings.json |
 
 ### Runtime CLI
 
 After installation or auto-update, NEXO adds `NEXO_HOME/bin` to your shell `PATH`. Open a new terminal and the `nexo` command provides operational tools:
 
 ```bash
-# Claude Code
-nexo chat                    # Launch Claude Code in the current directory
-nexo chat ~/claude           # Launch Claude Code in a specific directory
-
 # Personal Scripts
 nexo scripts list              # List your personal scripts
 nexo scripts run my-script     # Run a script with injected NEXO env
@@ -578,7 +625,7 @@ nexo doctor --tier runtime --json  # Machine-readable health report
 nexo doctor --fix              # Apply deterministic repairs
 ```
 
-Personal scripts live in `NEXO_HOME/scripts/` with inline metadata and are tracked in a first-class registry (SQLite). 9 MCP tools manage the full lifecycle: `nexo_personal_scripts_list`, `nexo_personal_script_create`, `nexo_personal_script_remove`, `nexo_personal_scripts_reconcile`, `nexo_personal_scripts_sync`, `nexo_personal_scripts_classify`, `nexo_personal_script_schedules`, `nexo_personal_script_unschedule`, `nexo_personal_scripts_ensure_schedules`. See `docs/writing-scripts.md` for details.
+Personal scripts live in `NEXO_HOME/scripts/` with inline metadata. See `docs/writing-scripts.md` for details.
 
 Skills v2 combine procedural guides with optional executable scripts. Personal skills live in `NEXO_HOME/skills/`, packaged core skills live in `NEXO_CODE/skills/` during development and `NEXO_HOME/skills-core/` in installed environments, and staged runtime copies live in `NEXO_HOME/skills-runtime/`. Execution is fully autonomous: Deep Sleep can evolve mature guide skills into executable drafts automatically, and runtime execution no longer waits for manual approval. See `docs/skills-v2.md` for the full model.
 
@@ -588,7 +635,7 @@ The Doctor system reads existing health artifacts (immune, watchdog, self-audit)
 
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
-- **Claude Opus (latest version) strongly recommended.** NEXO Brain provides 144+ MCP tools across 20+ categories. This cognitive load requires a top-tier model with large context window. Smaller models (Haiku, Sonnet) may struggle with tool selection and produce inconsistent results. Opus handles all 144+ tools without hesitation.
+- **Claude Opus (latest version) strongly recommended.** NEXO Brain provides 150+ MCP tools across 20+ categories. This cognitive load requires a top-tier model with large context window. Smaller models (Haiku, Sonnet) may struggle with tool selection and produce inconsistent results. Opus handles all 150+ tools without hesitation.
 - Python 3, Homebrew, and Claude Code are installed automatically if missing.
 
 ## Architecture
@@ -607,7 +654,7 @@ NEXO Brain separates **code** (immutable, in the repo or npm package) from **dat
 
 The plugin loader scans `src/plugins/` first (base), then `NEXO_HOME/plugins/` (personal override by filename). This dual-directory approach lets you extend NEXO without forking the repo.
 
-### 144+ MCP Tools across 20+ Categories
+### 150+ MCP Tools across 21+ Categories
 
 | Category | Count | Tools | Purpose |
 |----------|-------|-------|---------|
@@ -632,7 +679,10 @@ The plugin loader scans `src/plugins/` first (base), then `NEXO_HOME/plugins/` (
 | Adaptive & Somatic | 4 | adaptive_weights, adaptive_override, somatic_check, somatic_stats | Learned signal weights + pain memory per file |
 | Knowledge Graph | 4 | kg_query, kg_path, kg_neighbors, kg_stats | Bi-temporal entity-relationship graph |
 | Context Continuity | 2 | checkpoint_save, checkpoint_read | Auto-compaction session preservation |
-| Personal Scripts | 9 | personal_scripts_list, personal_script_create, personal_script_remove, personal_scripts_reconcile, personal_scripts_sync, personal_scripts_classify, personal_script_schedules, personal_script_unschedule, personal_scripts_ensure_schedules | First-class script registry with lifecycle, scheduling, and reconciliation |
+| Personal Scripts | 9 | sync, list, create, remove, schedules, unschedule, reconcile, classify, ensure_schedules | Script lifecycle management |
+| Skills | 12 | match, create, get, list, apply, approve, result, stats, evolution_candidates, merge, sync, featured | Reusable procedure library |
+| Schedule | 2 | add, status | Personal cron scheduling |
+| Doctor | 1 | doctor | Runtime diagnostics with --fix |
 | Update | 1 | update | Pull latest code, backup, migrate, verify (with rollback) |
 
 ### Plugin System
@@ -691,7 +741,7 @@ NEXO Brain is designed as an MCP server. Claude Code is the primary supported cl
 npx nexo-brain
 ```
 
-All 144+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
+All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
 
 ### OpenClaw
 
@@ -762,20 +812,9 @@ NEXO Brain works with any application that supports the MCP protocol. Configure
 | mcpservers.org | MCP Directory | [mcpservers.org](https://mcpservers.org) |
 | OpenClaw | Native Plugin | [openclaw.com](https://openclaw.ai) |
 | dev.to | Technical Article | [How I Applied Cognitive Psychology to AI Agents](https://dev.to/wazionapps/how-i-applied-cognitive-psychology-to-give-ai-agents-real-memory-2oce) |
+| Claude Code | Plugin (pending review) | Submitted to Anthropic's plugin marketplace |
 | nexo-brain.com | Official Website | [nexo-brain.com](https://nexo-brain.com) |
 
-## Inspired By
-
-NEXO Brain builds on ideas from several open-source projects. We're grateful for the research and implementations that inspired specific features:
-
-| Project | Inspired Features |
-|---------|------------------|
-| Vestige | HyDE query expansion, spreading activation, prediction error gating, memory dreaming, prospective memory |
-| ShieldCortex | Security pipeline (4-layer memory poisoning defense) |
-| Bicameral | Quarantine queue (trust promotion policy for new facts) |
-| claude-mem | Hook auto-capture (extracting decisions and facts from conversations) |
-| ClawMem | Co-activation reinforcement (memories retrieved together strengthen connections) |
-
 ## Support the Project
 
 If NEXO Brain is useful to you, consider:
@@ -787,31 +826,38 @@ If NEXO Brain is useful to you, consider:
 
 [![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 
-## Known Issues
-
-| Priority | Issue | Status |
-|----------|-------|--------|
-| P1 | Credentials stored in plaintext SQLite — protect with filesystem permissions | Mitigated: secret redaction in tool logs (v2.4.0) |
-| P2 | Dashboard has no authentication (localhost only) | By design — bind to localhost, no remote access |
-
 ## Changelog
 
-### v2.6.0 — Personal Scripts Registry, Plugin Marketplace, Orchestrator Decoupled (2026-04-03)
-- **Personal Scripts Registry**: First-class script tracking in SQLite with 9 MCP tools for full lifecycle management — create, list, remove, schedule, unschedule, reconcile, sync, classify.
-- **Orchestrator removed from core**: Day Orchestrator decoupled from the product. Power users keep it as a personal script. Reduces complexity for standard installs.
-- **Claude Code plugin structure**: `plugin.json` + entry point for Anthropic marketplace submission.
-- **`nexo chat`**: Official CLI command to launch Claude Code with NEXO as operator.
-- **Managed Evolution hardening**: Can now modify core behavior modules with rollback followups. Fixed false-positive watchdog tamper detection.
-- **Cron reliability**: Hardened recovery, TCC diagnostics, keepalive sync, disabled optional cron respect.
-- **Duplicate learning prevention**: Exact-title guard before insert.
+### v2.6.5 — Power Helper Hardening, Recovery Contracts (2026-04-04)
+- Power helper semantics explicit and safer: `always_on` = platform helper for best-effort background availability.
+- Catch-up recovery suppresses duplicate relaunches for in-flight `cron_runs`.
+- Runtime update/startup reconciles declared personal schedules automatically.
+
+### v2.6.3 — Cron Sync Fix, Hook Migration (2026-04-04)
+- Runtime cron sync skips same-file copies, avoiding `SameFileError` on synced runtimes.
+- Core hook migration normalizes legacy flat entries into Claude Code's required `matcher + hooks[]` format.
+
+### v2.6.2 — Startup Preflight, Personal Recovery, Power Policy (2026-04-04)
+- Startup preflight before `nexo chat` and server — safe local migrations, deferred remote updates.
+- Personal managed schedules can declare recovery contracts (wake/boot/catchup).
+- Persisted runtime power policy (`always_on`/`disabled`/`unset`). Installer and `nexo update` prompt once.
+- Packaged installs resolve update root correctly (fixes `vunknown`).
+
+### v2.6.0 — Personal Scripts Registry, Plugin Marketplace, Managed Evolution (2026-04-03)
+- **Personal scripts registry**: Scripts in `NEXO_HOME/scripts/` tracked in SQLite with metadata, categories, schedules. Full lifecycle: create, sync, reconcile, schedule, unschedule, remove.
+- **Orchestrator removed from core** (breaking): Was opt-in personal automation adding complexity for all users. Existing users keep their setup in `NEXO_HOME/scripts/`.
+- **Claude Code plugin structure**: `plugin.json`, entry point, packaging for marketplace submission.
+- **`nexo chat`**: Official command to launch Claude Code with NEXO as operator.
+- **Managed Evolution hardening**: Can modify core behavior modules with rollback followups.
+- Cron recovery hardened: TCC diagnostics, keepalive sync, personal schedule catchup.
 
 ### v2.5.0 — Runtime CLI, Doctor, Skills v2, Day Orchestrator (2026-04-03)
 - **Runtime CLI** (`nexo`): New operational CLI separate from installer. `nexo scripts list/run/doctor/call` for personal scripts, `nexo doctor` for diagnostics, `nexo skills apply` for executable skills, `nexo update` for one-step sync.
 - **Unified Doctor**: Modular diagnostic system with boot/runtime/deep tiers. Report-only by default, deterministic `--fix` mode. MCP tool `nexo_doctor`. LaunchAgent schedule drift detection and reconciliation.
 - **Skills v2**: Executable skills with guide/execute/hybrid modes. Security levels (read-only/local/remote) with explicit approval. Core vs personal vs community directories. Deep Sleep auto-evolution integration.
-- **Day Orchestrator**: Autonomous NEXO cycles every 15 min (8:00-23:00). *(Removed from core in v2.6.0 — available as personal script.)*
+- **Day Orchestrator**: Autonomous NEXO cycles every 15 min (8:00-23:00). Launches Claude Code headless with full MCP. Checks followups, emails, infra — acts autonomously, emails user only when needed. Opt-in.
 - **Dashboard always-on**: Web UI at localhost:6174 as persistent LaunchAgent. 23 modules, Jinja2 templating, dark theme. Opt-in.
-- **Personal Scripts Framework**: Auto-discovery in NEXO_HOME/scripts/, inline metadata, runtime detection, forbidden-pattern validation. *(Promoted to first-class registry in v2.6.0.)*
+- **Personal Scripts Framework**: Auto-discovery in NEXO_HOME/scripts/, inline metadata, runtime detection, forbidden-pattern validation, vendorable helper, template.
 - Configurable operator name (UserContext singleton), watchdog normalized to 30 min, LaunchAgent drift fix.
 
 ### v2.4.0 — Skills, Cron Scheduler, Security, Full Audit (2026-04-03)
@@ -836,9 +882,9 @@ If NEXO Brain is useful to you, consider:
 - **Auto-diary**: 3-layer system — PostToolUse every 10 calls, PreCompact emergency save, heartbeat DIARY_OVERDUE signal.
 - **CLAUDE.md version tracker**: Section markers enable safe core updates without losing user customizations.
 - **schedule.json**: Customizable process schedules with timezone support and `auto_update` flag.
-- **14 autonomous processes**: Added auto-close-sessions, synthesis, backup, tcc-approve, prevent-sleep (cross-platform).
+- **15 autonomous processes**: Added auto-close-sessions, synthesis, backup, tcc-approve, prevent-sleep (cross-platform).
 - **7 hooks**: SessionStart (timestamp + briefing), Stop, PostToolUse (capture + inbox), PreCompact, PostCompact.
-- **144+ MCP tools**: Added `nexo_update` tool for manual updates with rollback.
+- **150+ MCP tools**: Added `nexo_update` tool for manual updates with rollback.
 - **Lambda fix**: Decay values were 24x too aggressive (STM: 7h to 7d, LTM: 2.4d to 60d).
 - **Guard scoping**: Was returning 35+ irrelevant blocking rules; now scoped to area and gated to high/critical.
 - **12 rounds of external audit**: ~60 findings resolved.

package/bin/nexo-brain.js

@@ -31,6 +31,7 @@ const LAUNCH_AGENTS = path.join(
   "Library",
   "LaunchAgents"
 );
+const MACOS_FDA_SETTINGS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
 
 function isEphemeralInstall(nexoHome) {
   const homeDir = require("os").homedir();
@@ -114,6 +115,139 @@ function logMacPermissionsNotice(nexoHome, pythonPath = "") {
   log("  System Settings → Privacy & Security → Full Disk Access");
 }
 
+function getRuntimePythonTargets(pythonPath = "") {
+  const candidates = [];
+  const venvPy = path.join(NEXO_HOME, ".venv", "bin", "python3");
+  if (fs.existsSync(venvPy)) candidates.push(venvPy);
+  if (pythonPath) candidates.push(pythonPath);
+  const discovered = run("which python3") || run("which python") || "";
+  if (discovered) candidates.push(discovered);
+  return [...new Set(candidates.filter(Boolean))];
+}
+
+function detectFullDiskAccessReasons(nexoHome) {
+  if (process.platform !== "darwin") return [];
+  const reasons = [];
+  if (isProtectedMacPath(nexoHome)) {
+    reasons.push(`NEXO_HOME is inside a protected macOS folder: ${nexoHome}`);
+  }
+
+  const logsDir = path.join(nexoHome, "logs");
+  if (fs.existsSync(logsDir)) {
+    const candidates = fs.readdirSync(logsDir).filter((name) => name.endsWith("-stderr.log"));
+    for (const name of candidates) {
+      try {
+        const text = fs.readFileSync(path.join(logsDir, name), "utf8");
+        if (text.includes("Operation not permitted")) {
+          reasons.push(`Recent background job stderr hit 'Operation not permitted' (${name})`);
+          break;
+        }
+      } catch {}
+    }
+  }
+  return reasons;
+}
+
+function probeFullDiskAccess(nexoHome) {
+  if (process.platform !== "darwin") {
+    return { checked: false, granted: null, probePath: "", message: "macOS-only" };
+  }
+
+  const candidates = [
+    path.join(require("os").homedir(), "Library", "Application Support", "com.apple.TCC", "TCC.db"),
+    path.join(require("os").homedir(), "Library", "Mail"),
+    path.join(require("os").homedir(), "Library", "Messages"),
+    path.join(require("os").homedir(), "Library", "Safari"),
+    path.join(require("os").homedir(), "Library", "Application Support", "AddressBook"),
+  ].filter((item) => fs.existsSync(item));
+
+  if (isProtectedMacPath(nexoHome)) candidates.push(nexoHome);
+  if (!candidates.length) {
+    return { checked: false, granted: null, probePath: "", message: "No probe path available." };
+  }
+
+  const seen = new Set();
+  for (const candidate of candidates) {
+    if (!candidate || seen.has(candidate)) continue;
+    seen.add(candidate);
+    const result = spawnSync("/bin/bash", [
+      "-lc",
+      'TARGET="$1"; if [ -d "$TARGET" ]; then ls "$TARGET" >/dev/null 2>&1; else head -c 1 "$TARGET" >/dev/null 2>&1; fi',
+      "_",
+      candidate,
+    ], { encoding: "utf8" });
+    if (result.status === 0) {
+      return { checked: true, granted: true, probePath: candidate, message: "" };
+    }
+  }
+  return { checked: true, granted: false, probePath: candidates[0], message: "Could not verify Full Disk Access yet." };
+}
+
+async function maybeConfigureFullDiskAccess(schedule, useDefaults, pythonPath = "") {
+  const current = String((schedule && schedule.full_disk_access_status) || "unset").toLowerCase();
+  schedule.full_disk_access_status_version = 1;
+  const reasons = detectFullDiskAccessReasons(NEXO_HOME);
+  schedule.full_disk_access_reasons = reasons;
+
+  if (process.platform !== "darwin" || !reasons.length) {
+    fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
+    return schedule;
+  }
+
+  if (current === "granted") {
+    const probe = probeFullDiskAccess(NEXO_HOME);
+    if (probe.granted) {
+      fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
+      return schedule;
+    }
+    schedule.full_disk_access_status = "later";
+  } else if (current === "declined") {
+    fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
+    return schedule;
+  }
+
+  if (useDefaults || !process.stdin.isTTY || !process.stdout.isTTY) {
+    schedule.full_disk_access_status = current === "granted" ? "later" : current || "unset";
+    fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
+    return schedule;
+  }
+
+  console.log("");
+  log("Optional macOS Full Disk Access guidance:");
+  log("macOS does not allow granting this automatically. NEXO can only open the correct System Settings screen and verify best effort.");
+  log("Reason(s) detected:");
+  reasons.forEach((item) => log(`  - ${item}`));
+  log("If you proceed, add your terminal app and, if needed for background jobs, these binaries:");
+  log("  - /bin/bash");
+  getRuntimePythonTargets(pythonPath).forEach((item) => log(`  - ${item}`));
+
+  const answer = (await ask("  Open Full Disk Access setup now? [y/N/later]: ")).trim().toLowerCase();
+  if (answer === "y" || answer === "yes") {
+    spawnSync("open", [MACOS_FDA_SETTINGS_URL], { stdio: "ignore" });
+    log("Opened System Settings → Privacy & Security → Full Disk Access.");
+    const followUp = (await ask("  Press Enter after granting it, or type later to skip for now: ")).trim().toLowerCase();
+    if (followUp === "later" || followUp === "l") {
+      schedule.full_disk_access_status = "later";
+    } else {
+      const probe = probeFullDiskAccess(NEXO_HOME);
+      if (probe.granted) {
+        schedule.full_disk_access_status = "granted";
+        log(`Full Disk Access verified via ${probe.probePath}.`);
+      } else {
+        schedule.full_disk_access_status = "later";
+        log("Could not verify Full Disk Access yet. NEXO will remind you later if background jobs still hit TCC.");
+      }
+    }
+  } else if (answer === "later" || answer === "l" || answer === "") {
+    schedule.full_disk_access_status = "later";
+  } else {
+    schedule.full_disk_access_status = "declined";
+  }
+
+  fs.writeFileSync(path.join(NEXO_HOME, "config", "schedule.json"), JSON.stringify(schedule, null, 2));
+  return schedule;
+}
+
 // ══════════════════════════════════════════════════════════════════════════════
 // CORE PROCESS & HOOK DEFINITIONS
 // All core nightly/periodic processes and all 8 core hooks that make NEXO functional.
@@ -295,7 +429,10 @@ function getDefaultSchedule(timezone) {
     timezone: timezone || "UTC",
     auto_update: true,
     power_policy: "unset",
-    power_policy_version: 1,
+    power_policy_version: 2,
+    full_disk_access_status: "unset",
+    full_disk_access_status_version: 1,
+    full_disk_access_reasons: [],
     processes: {
       "cognitive-decay": { hour: 3, minute: 0 },
       "postmortem": { hour: 23, minute: 30 },
@@ -315,14 +452,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 +472,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;
 }
@@ -839,6 +981,7 @@ async function main() {
         let migSchedule = loadOrCreateSchedule(NEXO_HOME);
         migSchedule = await maybeConfigurePowerPolicy(migSchedule, useDefaults);
         const migPython = findVenvPython(NEXO_HOME) || "python3";
+        migSchedule = await maybeConfigureFullDiskAccess(migSchedule, useDefaults, migPython);
         let migOptionals = {};
         try {
           const optFile = path.join(NEXO_HOME, "config", "optionals.json");
@@ -1064,9 +1207,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 +1239,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 +1271,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 +1303,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 +1335,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 +1367,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",
@@ -2111,6 +2254,7 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
   log("Setting up automated processes...");
   let schedule = loadOrCreateSchedule(NEXO_HOME);
   schedule = await maybeConfigurePowerPolicy(schedule, useDefaults);
+  schedule = await maybeConfigureFullDiskAccess(schedule, useDefaults, python);
   const enabledOptionals = { dashboard: doDashboard };
   if (isEphemeralInstall(NEXO_HOME)) {
     log("Ephemeral HOME/NEXO_HOME detected — skipping LaunchAgents installation.");