nexo-brain 7.9.2 → 7.9.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.2",
+  "version": "7.9.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,11 @@
 
 [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.9.2` is the current packaged-runtime line. Patch release that completes the Brain semantic-router site migration: the remaining decision callers now route through `semantic_router.route(...)` with named `decision_kind` policies (`r20_constant_change`, `r34_identity_coherence`, `t4_r15`, `t4_r23e`, `t4_r23f`, `t4_r23h`, `followup_operator_attention`, `drive_signal_type`, `drive_area`, `reply_event_type`, `query_intent`, and `sentiment_intent`). Brain now owns model choice, thresholds, and fallback behaviour centrally instead of each caller carrying its own classifier policy. The patch also fixes packaged headless Guardian map loading: `enforcement_engine` and `agent_runner` now check the installed core directory (`~/.nexo/core/tool-enforcement-map.json`) so followup-runner, morning-agent, digest, and email-monitor load the map instead of falling back to unguarded subprocess execution. Targeted verification: 100 semantic/router/enforcer tests, 125 Drive/cognitive/productization tests, and release-readiness passing.
+Version `7.9.4` is the current packaged-runtime line. Patch release that blocks the Brain 7.9.3 + Desktop 0.28.2 diary regression: canonical lifecycle plans now require real `session_diary` evidence (`wait_for_diary_write`) before `stop_session`, and canonical completion is rejected/retryable without that diary row. It also fixes npm CLI onboarding so `nexo-brain --version` and subcommands never launch the wizard when legacy/v2 calibration is already valid, commits setup calibration atomically only after the wizard completes, and adds `nexo-brain warmup-models` so install/update paths predownload the local mDeBERTa/BGE/reranker models. Verification: full Brain pytest (`2189 passed, 3 skipped, 1 xfailed, 5 xpassed`), release-readiness, npm pack dry-run, and coordinated Desktop v0.28.3 checks.
+
+Previously in `7.9.3`: patch release that hardens Brain's canonical lifecycle plan for Desktop close/archive/delete/app-exit diary guarantees: `canonical_actions` now publish the v2 canonical shape (`type` plus `payload.prompt`) while keeping one-release compatibility mirrors (`kind` plus top-level `prompt`) for older Desktop clients. This lets Desktop execute resume → diary prompt → stop with one exact owner per lifecycle event and preserve Brain-side dedupe by event id. Targeted verification: `pytest tests/test_lifecycle_events.py` (25 passing) plus release-readiness after artifact sync.
+
+Previously in `7.9.2`: patch release that completes the Brain semantic-router site migration: the remaining decision callers now route through `semantic_router.route(...)` with named `decision_kind` policies (`r20_constant_change`, `r34_identity_coherence`, `t4_r15`, `t4_r23e`, `t4_r23f`, `t4_r23h`, `followup_operator_attention`, `drive_signal_type`, `drive_area`, `reply_event_type`, `query_intent`, and `sentiment_intent`). Brain now owns model choice, thresholds, and fallback behaviour centrally instead of each caller carrying its own classifier policy. The patch also fixes packaged headless Guardian map loading: `enforcement_engine` and `agent_runner` now check the installed core directory (`~/.nexo/core/tool-enforcement-map.json`) so followup-runner, morning-agent, digest, and email-monitor load the map instead of falling back to unguarded subprocess execution. Targeted verification: 100 semantic/router/enforcer tests, 125 Drive/cognitive/productization tests, and release-readiness passing.
 
 Previously in `7.9.0`: minor release that ships the foundation of the semantic stack (router + reasoner + CLI) under the ONEPASS LLM Coverage plan, plus two product-bug fixes observed in the wild on 2026-04-23. New `src/semantic_router.py` exposes 18 named `decision_kinds` (13 textual + 5 code-aware) with a per-kind policy table and the layer chain `fast_local → semantic_reasoner → remote_fallback`. New `src/semantic_reasoner.py` adds Mode A (`multipass_local`: reuses the mDeBERTa pin with three prompt-perturbed passes + majority vote + 0.75 floor) and Mode B (`cached_llm`: wrapper over `call_model_raw` with a pid+uuid atomic-write 24h-TTL disk cache at `~/.nexo/runtime/operations/semantic-reasoner-cache.json`, SHA-256 keyed by `decision_kind` + normalized input, LRU-bounded at 2000 entries, corrupt entries dropped on read). New `scripts/semantic-classify.py` JSON-in JSON-out CLI lets external MCP clients (including the closed-source NEXO Desktop companion) query Brain as the single semantic authority. New `NEXO_SEMANTIC_REASONER` kill switch (`0`/`off`/`false`/`no`/`disable`/`disabled`) honours the plan mandate for a runtime opt-out separate from `NEXO_LOCAL_CLASSIFIER`. Bug fixes: `bin/nexo-brain.js` upgrade flow now copies `templates/` root the same way fresh install and same-version refresh already did (Maria iMac 7.1.10→7.8.1 upgrade had lost 27 core-prompts templates and broken post-update import verification); and `tool-enforcement-map.json` `nexo_startup.enforcement.inject_prompt` now instructs the model to preload the 13 `mcp__nexo__*` protocol tools via `ToolSearch` before calling `nexo_startup` when the host MCP client defers tool schemas (Claude Code with many MCPs installed). Audit-driven hardening: router/reasoner defensively use `getattr` over the `call_model_raw` module and add a trailing `except Exception` so provider errors degrade with `remote_error` instead of propagating; cache writes use pid+uuid tmp + `fsync` + `os.replace` to survive concurrent writers; `NEXO_SEMANTIC_REASONER_TTL` parse tolerates malformed values. Tests: +50 (22 router, 20 reasoner, 8 CLI). Per-site migration of existing callers (`session_end_intent`, `r14`, `r16`, `r17`, `r20`, `r34`, T4 gates, `tools_drive`, `nexo-followup-runner`) is explicitly deferred to follow-up patch releases and tracked as `NF-SEMANTIC-ROUTER-SITE-MIGRATION`; nothing in this release changes the behaviour of the existing callers. Companion coordinated release: NEXO Desktop v0.28.0.
 

package/bin/nexo-brain.js

@@ -177,13 +177,27 @@ function isEphemeralInstall(nexoHome) {
     .some((candidate) => Array.from(tempRoots).some((root) => isWithin(candidate, root)));
 }
 
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout,
-});
+let rl = null;
+
+function getReadline() {
+  if (!rl) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+  }
+  return rl;
+}
 
 function ask(question) {
-  return new Promise((resolve) => rl.question(question, resolve));
+  return new Promise((resolve) => getReadline().question(question, resolve));
+}
+
+function closeReadline() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
 }
 
 function run(cmd, opts = {}) {
@@ -198,6 +212,277 @@ function log(msg) {
   console.log(`  ${msg}`);
 }
 
+function readPackageJson() {
+  return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+}
+
+function writeJsonAtomic(targetPath, payload) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const tmpPath = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.tmp`
+  );
+  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2) + "\n");
+  fs.renameSync(tmpPath, targetPath);
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function calibrationPathCandidates(nexoHome) {
+  return [
+    path.join(nexoHome, "personal", "brain", "calibration.json"),
+    path.join(nexoHome, "brain", "calibration.json"),
+  ];
+}
+
+function readRuntimeCalibration(nexoHome = NEXO_HOME) {
+  for (const filePath of calibrationPathCandidates(nexoHome)) {
+    if (!fs.existsSync(filePath)) continue;
+    const payload = readJsonFile(filePath);
+    if (payload && typeof payload === "object") {
+      return { path: filePath, payload };
+    }
+  }
+  return { path: null, payload: null };
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isPlaceholderUserName(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized === "" || normalized === "usuario";
+}
+
+function isOnboardingComplete(calibration) {
+  if (!calibration || typeof calibration !== "object") return false;
+  const user = calibration.user && typeof calibration.user === "object" ? calibration.user : {};
+  const name = user.name;
+  const language = user.language || calibration.language;
+  const meta = calibration.meta && typeof calibration.meta === "object" ? calibration.meta : {};
+
+  if (meta.onboarding_completed === true) {
+    return nonEmptyString(name) && nonEmptyString(language);
+  }
+
+  // Legacy fallback: v7.8/v7.9-era calibration files may not carry the
+  // current schema marker, but a real operator name + language is enough to
+  // prove the setup was completed. Placeholder defaults stay incomplete.
+  return nonEmptyString(name) && !isPlaceholderUserName(name) && nonEmptyString(language);
+}
+
+function hasPartialPlaceholderCalibration(calibration) {
+  if (!calibration || typeof calibration !== "object") return false;
+  const meta = calibration.meta && typeof calibration.meta === "object" ? calibration.meta : {};
+  if (meta.onboarding_completed === true) return false;
+  const user = calibration.user && typeof calibration.user === "object" ? calibration.user : {};
+  const name = user.name;
+  const language = user.language || calibration.language;
+  return isPlaceholderUserName(name) || !nonEmptyString(language);
+}
+
+function ensureOnboardingCompletionMarker(nexoHome = NEXO_HOME) {
+  const record = readRuntimeCalibration(nexoHome);
+  if (!record.path || !isOnboardingComplete(record.payload)) {
+    return { changed: false, complete: false, path: record.path };
+  }
+  const meta = record.payload.meta && typeof record.payload.meta === "object"
+    ? { ...record.payload.meta }
+    : {};
+  if (meta.onboarding_completed === true) {
+    return { changed: false, complete: true, path: record.path };
+  }
+  const next = {
+    ...record.payload,
+    version: Math.max(Number(record.payload.version) || 1, 2),
+    meta: {
+      ...meta,
+      onboarding_completed: true,
+      onboarding_completed_at: meta.onboarding_completed_at || new Date().toISOString(),
+      migrated_from_legacy_calibration: true,
+    },
+  };
+  writeJsonAtomic(record.path, next);
+  return { changed: true, complete: true, path: record.path };
+}
+
+const WARMUP_SCRIPT = path.join(__dirname, "..", "src", "model_warmup.py");
+const WARMUP_PIP_PACKAGES = [
+  "transformers",
+  "torch",
+  "sentencepiece",
+  "sentence-transformers",
+];
+const WARMUP_TIMEOUT_MS = 60 * 60 * 1000;
+
+function shouldSkipModelWarmup() {
+  const flag = String(process.env.NEXO_SKIP_MODEL_WARMUP || "").trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(flag);
+}
+
+function resolveSystemPython() {
+  return run("which python3") || run("which python") || "python3";
+}
+
+function ensureWarmupPython(nexoHome = NEXO_HOME) {
+  const existing = findVenvPython(nexoHome);
+  if (existing) return existing;
+
+  const basePython = resolveSystemPython();
+  const venvPath = path.join(nexoHome, ".venv");
+  const venvPython = process.platform === "win32"
+    ? path.join(venvPath, "Scripts", "python.exe")
+    : path.join(venvPath, "bin", "python3");
+  fs.mkdirSync(nexoHome, { recursive: true });
+  if (!fs.existsSync(venvPython)) {
+    log("  Creating Python virtual environment for model warmup...");
+    const result = spawnSync(basePython, ["-m", "venv", venvPath], { stdio: "inherit", timeout: 120000 });
+    if (result.status !== 0) {
+      throw new Error("could not create Python virtual environment for model warmup");
+    }
+  }
+  return venvPython;
+}
+
+function installWarmupPythonDependencies(pythonPath, { quiet = false, installRuntimeDeps = true } = {}) {
+  const requirementsFile = path.join(__dirname, "..", "src", "requirements.txt");
+  const pipCommon = ["-m", "pip", "install"];
+  if (quiet) pipCommon.push("--quiet");
+  const stdio = quiet ? "pipe" : "inherit";
+
+  if (installRuntimeDeps && fs.existsSync(requirementsFile)) {
+    const reqResult = spawnSync(
+      pythonPath,
+      [...pipCommon, "-r", requirementsFile],
+      { stdio, timeout: WARMUP_TIMEOUT_MS }
+    );
+    if (reqResult.status !== 0) {
+      throw new Error("failed to install runtime Python dependencies for model warmup");
+    }
+  }
+
+  const classifierResult = spawnSync(
+    pythonPath,
+    [...pipCommon, ...WARMUP_PIP_PACKAGES],
+    { stdio, timeout: WARMUP_TIMEOUT_MS }
+  );
+  if (classifierResult.status !== 0) {
+    throw new Error("failed to install local classifier dependencies for model warmup");
+  }
+}
+
+function runModelWarmup(pythonPath, {
+  nexoHome = NEXO_HOME,
+  dryRun = false,
+  json = false,
+  strict = true,
+  quiet = false,
+} = {}) {
+  if (!fs.existsSync(WARMUP_SCRIPT)) {
+    throw new Error(`model warmup script not found: ${WARMUP_SCRIPT}`);
+  }
+  const args = [WARMUP_SCRIPT];
+  if (dryRun) args.push("--dry-run");
+  if (json) args.push("--json");
+  if (strict) args.push("--strict");
+  const result = spawnSync(pythonPath, args, {
+    cwd: path.join(__dirname, "..", "src"),
+    env: { ...process.env, NEXO_HOME: nexoHome, NEXO_CODE: path.join(__dirname, "..", "src") },
+    stdio: json ? "pipe" : (quiet ? "pipe" : "inherit"),
+    encoding: json || quiet ? "utf8" : undefined,
+    timeout: WARMUP_TIMEOUT_MS,
+  });
+  if (json && result.stdout) process.stdout.write(result.stdout);
+  if (json && result.stderr) process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    const details = json || quiet
+      ? String(result.stderr || result.stdout || "").trim()
+      : "";
+    throw new Error(details || `model warmup failed with exit ${result.status}`);
+  }
+}
+
+function runMandatoryModelWarmup(pythonPath, nexoHome = NEXO_HOME, { reason = "install", installRuntimeDeps = true } = {}) {
+  if (shouldSkipModelWarmup()) {
+    log(`Model warmup skipped by NEXO_SKIP_MODEL_WARMUP during ${reason}.`);
+    return;
+  }
+  log(`Warming up local Brain/Desktop models (${reason})...`);
+  installWarmupPythonDependencies(pythonPath, { quiet: false, installRuntimeDeps });
+  runModelWarmup(pythonPath, { nexoHome, strict: true });
+  log("Local model warmup complete.");
+}
+
+async function runWarmupModelsCommand(args) {
+  const dryRun = args.includes("--dry-run");
+  const json = args.includes("--json");
+  const force = args.includes("--force");
+  const quiet = args.includes("--postinstall") || args.includes("--quiet");
+
+  if (shouldSkipModelWarmup() && !force) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ ok: true, skipped: true, reason: "NEXO_SKIP_MODEL_WARMUP" }) + "\n");
+    } else {
+      log("Model warmup skipped by NEXO_SKIP_MODEL_WARMUP.");
+    }
+    return;
+  }
+
+  const pythonPath = dryRun ? resolveSystemPython() : ensureWarmupPython(NEXO_HOME);
+  if (!dryRun) {
+    installWarmupPythonDependencies(pythonPath, { quiet });
+  }
+  runModelWarmup(pythonPath, {
+    nexoHome: NEXO_HOME,
+    dryRun,
+    json,
+    strict: !args.includes("--best-effort"),
+    quiet,
+  });
+}
+
+function printHelp() {
+  const version = readPackageJson().version;
+  console.log(`nexo-brain ${version}`);
+  console.log("");
+  console.log("Usage:");
+  console.log("  nexo-brain [--yes|--skip|--defaults]");
+  console.log("  nexo-brain --version");
+  console.log("  nexo-brain warmup-models [--dry-run] [--json] [--force]");
+}
+
+async function maybeHandleTopLevelCommand(argv = process.argv.slice(2)) {
+  if (argv.includes("--version") || argv.includes("-v") || argv[0] === "version") {
+    console.log(`nexo-brain ${readPackageJson().version}`);
+    return true;
+  }
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    printHelp();
+    return true;
+  }
+  if (argv[0] === "warmup-models") {
+    await runWarmupModelsCommand(argv.slice(1));
+    return true;
+  }
+
+  const setupFlags = new Set(["--defaults", "--yes", "--skip", "-y"]);
+  const unknownCommand = argv.find((arg) => !setupFlags.has(arg));
+  if (unknownCommand && !unknownCommand.startsWith("-")) {
+    console.error(`Unknown nexo-brain command: ${unknownCommand}`);
+    console.error("Run 'nexo-brain --help' for usage.");
+    process.exitCode = 2;
+    return true;
+  }
+  return false;
+}
+
 function duplicateArtifactCanonicalName(name) {
   const ext = path.extname(name);
   const stem = ext ? name.slice(0, -ext.length) : name;
@@ -1946,7 +2231,7 @@ WantedBy=timers.target
   }
 }
 
-async function main() {
+async function runSetup() {
   // Non-interactive mode: --defaults, --yes, --skip, or -y all skip prompts
   // and apply the recommended defaults end-to-end (v6.0.0 adds --skip).
   const useDefaults = process.argv.includes("--defaults")
@@ -1993,12 +2278,22 @@ async function main() {
     process.exit(1);
   }
 
+  const onboardingMigration = ensureOnboardingCompletionMarker(NEXO_HOME);
+  if (onboardingMigration.changed) {
+    log("Migrated legacy calibration completion marker.");
+  } else {
+    const calibrationRecord = readRuntimeCalibration(NEXO_HOME);
+    if (hasPartialPlaceholderCalibration(calibrationRecord.payload)) {
+      log("Incomplete calibration detected; restarting onboarding cleanly.");
+    }
+  }
+
   // Auto-migration: detect existing installation
   const versionFile = path.join(NEXO_HOME, "version.json");
   if (fs.existsSync(versionFile)) {
     try {
       const installed = JSON.parse(fs.readFileSync(versionFile, "utf8"));
-      const currentPkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+      const currentPkg = readPackageJson();
       const installedVersion = installed.version || "0.0.0";
       const currentVersion = currentPkg.version;
 
@@ -2079,6 +2374,9 @@ async function main() {
           log("  Python dependencies reconciled.");
         }
 
+        const migPythonForWarmup = findVenvPython(NEXO_HOME) || "python3";
+        runMandatoryModelWarmup(migPythonForWarmup, NEXO_HOME, { reason: "update", installRuntimeDeps: false });
+
         // Update plugins (all .py files in plugins/)
         const pluginsSrc = path.join(srcDir, "plugins");
         const pluginsDest = path.join(NEXO_HOME, "core", "plugins");
@@ -2246,11 +2544,12 @@ async function main() {
         log(`Migration complete: v${installedVersion} → v${currentVersion}`);
         log("Your data (memories, learnings, preferences) is untouched.");
         console.log("");
-        rl.close();
+        closeReadline();
         return;
       }
 
       // Same version — backfill crons/ if missing (for installs before crons was shipped)
+      const syncPython = findVenvPython(NEXO_HOME) || run("which python3") || "python3";
       const cronsDest = resolveRuntimeCronsDir(NEXO_HOME);
       const cronsSrc = path.join(__dirname, "..", "src", "crons");
       if (fs.existsSync(cronsSrc)) {
@@ -2268,7 +2567,6 @@ async function main() {
         log("Refreshed crons/ directory.");
 
         const cronSyncPath = path.join(cronsSrc, "sync.py");
-        const syncPython = findVenvPython(NEXO_HOME) || run("which python3") || "python3";
         if (fs.existsSync(cronSyncPath)) {
           const syncResult = spawnSync(syncPython, [cronSyncPath], {
             env: { ...process.env, NEXO_HOME, NEXO_CODE: path.join(__dirname, "..", "src") },
@@ -2340,10 +2638,11 @@ async function main() {
         throw new Error(`F0.6 layout finalization failed: ${syncLayoutFinalize.error}`);
       }
 
+      runMandatoryModelWarmup(syncPython, NEXO_HOME, { reason: "repair" });
       logMacPermissionsNotice(NEXO_HOME, syncPython);
 
       log(`Already at v${currentVersion}. No migration needed.`);
-      rl.close();
+      closeReadline();
       return;
     } catch (e) {
       // Version file corrupt — proceed with fresh install
@@ -2732,18 +3031,14 @@ async function main() {
       report_style: "essentials_only",
       execution_first: true,
     },
-    meta: {},
+    meta: {
+      onboarding_completed: true,
+      onboarding_completed_at: new Date().toISOString(),
+    },
     auto_install: "ask", // updated later if user answers P11
     calibrated_at: new Date().toISOString(),
   };
-  // Ensure NEXO_HOME and brain dir exist before writing calibration
   const runtimeBrainDir = resolveRuntimeBrainDir(NEXO_HOME);
-  fs.mkdirSync(NEXO_HOME, { recursive: true });
-  fs.mkdirSync(runtimeBrainDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(runtimeBrainDir, "calibration.json"),
-    JSON.stringify(calibration, null, 2)
-  );
 
   // Step 5: Deep scan (P9) — v6.0.0 defaults flip to ON when running in
   // --yes/--skip mode; the interactive prompt below defaults to "yes" too
@@ -2792,28 +3087,18 @@ async function main() {
     console.log("");
   }
 
-  // Persist the updated calibration (auto_install may have changed post-write above).
-  try {
-    fs.writeFileSync(
-      path.join(runtimeBrainDir, "calibration.json"),
-      JSON.stringify(calibration, null, 2)
-    );
-  } catch (_) {}
+  // Commit calibration only after the wizard completed. This prevents Ctrl-C
+  // from leaving placeholder defaults that look like real onboarding.
+  fs.mkdirSync(NEXO_HOME, { recursive: true });
+  writeJsonAtomic(path.join(runtimeBrainDir, "calibration.json"), calibration);
 
   if (smokeTestMode) {
     // Pytest fresh-install smoke only needs to prove that the non-interactive
     // onboarding path writes the current calibration shape. Skip the rest of
     // the heavy bootstrap (client installs, pip, scan, LaunchAgents) so the
     // smoke does not sit on long dependency timeouts inside sandboxes.
-    try {
-      fs.mkdirSync(runtimeBrainDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(runtimeBrainDir, "calibration.json"),
-        JSON.stringify(calibration, null, 2)
-      );
-    } catch (_) {}
     log("Smoke test mode detected — wrote calibration and skipped heavy bootstrap.");
-    rl.close();
+    closeReadline();
     return;
   }
 
@@ -2862,6 +3147,7 @@ async function main() {
     python = venvPython;
   }
   log("Dependencies installed.");
+  runMandatoryModelWarmup(python, NEXO_HOME, { reason: "install", installRuntimeDeps: false });
 
   // Step 4: Create ~/.nexo/
   log("Setting up NEXO home...");
@@ -3915,10 +4201,18 @@ See ~/.nexo/ for configuration.
   console.log(`  \u255A${"═".repeat(bw - 2)}\u255D`);
   console.log("");
 
-  rl.close();
+  closeReadline();
+}
+
+async function main() {
+  const handled = await maybeHandleTopLevelCommand();
+  if (!handled) {
+    await runSetup();
+  }
 }
 
 main().catch((err) => {
+  closeReadline();
   console.error("Setup failed:", err.message);
   process.exit(1);
 });

package/bin/postinstall.js

@@ -8,15 +8,29 @@
 
 const fs = require("fs");
 const path = require("path");
+const { execFileSync } = require("child_process");
 
 const NEXO_HOME = process.env.NEXO_HOME || path.join(require("os").homedir(), ".nexo");
 const VERSION_FILE = path.join(NEXO_HOME, "version.json");
+const INSTALLER = path.join(__dirname, "nexo-brain.js");
 
 if (process.env.NEXO_SKIP_POSTINSTALL === "1") {
   // Called during rollback — skip migration to avoid loops
   process.exit(0);
 }
 
+function runModelWarmup(reason) {
+  if (process.env.NEXO_SKIP_MODEL_WARMUP === "1") {
+    console.log(`\n  NEXO Brain: model warmup skipped by NEXO_SKIP_MODEL_WARMUP (${reason}).`);
+    return;
+  }
+  console.log(`\n  NEXO Brain: warming up local models (${reason})...`);
+  execFileSync(process.execPath, [INSTALLER, "warmup-models", "--postinstall"], {
+    stdio: "inherit",
+    env: { ...process.env, NEXO_POSTINSTALL: "1", NEXO_HOME: NEXO_HOME }
+  });
+}
+
 if (fs.existsSync(VERSION_FILE)) {
   // Existing installation — run auto-migration silently
   const installed = JSON.parse(fs.readFileSync(VERSION_FILE, "utf8"));
@@ -32,9 +46,8 @@ if (fs.existsSync(VERSION_FILE)) {
   // Run the main installer in --yes mode (non-interactive)
   // It will detect the existing version and do migration only
   // Let errors propagate so npm reports the failure correctly
-  const { execFileSync } = require("child_process");
   try {
-    execFileSync(process.execPath, [path.join(__dirname, "nexo-brain.js"), "--yes"], {
+    execFileSync(process.execPath, [INSTALLER, "--yes"], {
       stdio: "inherit",
       env: { ...process.env, NEXO_POSTINSTALL: "1", NEXO_HOME: NEXO_HOME }
     });
@@ -44,6 +57,14 @@ if (fs.existsSync(VERSION_FILE)) {
     process.exit(1);
   }
 } else {
+  try {
+    runModelWarmup("fresh install");
+  } catch (e) {
+    console.error(`\n  NEXO Brain: model warmup FAILED — ${e.message}`);
+    console.error("  Set NEXO_SKIP_MODEL_WARMUP=1 only for CI/offline testing, then run 'nexo-brain warmup-models'.");
+    process.exit(1);
+  }
+
   // Fresh install — just show instructions
   console.log("\n  ╔════════════════════════════════════════════╗");
   console.log("  ║  NEXO Brain installed successfully!       ║");

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.2",
+  "version": "7.9.4",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO Brain \u2014 Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
+  "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",
   "bin": {
-    "nexo-brain": "./bin/nexo-brain.js",
-    "nexo": "./bin/nexo.js"
+    "nexo-brain": "bin/nexo-brain.js",
+    "nexo": "bin/nexo.js"
   },
   "keywords": [
     "claude-code",

package/src/cli.py

@@ -3104,6 +3104,14 @@ def main():
         help="JSON array of per-action outcomes, e.g. '[{\"action_id\":\"a1\",\"status\":\"ok\"}]'",
     )
 
+    lwait_p = lifecycle_sub.add_parser(
+        "wait-for-diary",
+        help="v7.9: wait for concrete session_diary evidence before canonical stop_session",
+    )
+    lwait_p.add_argument("--event-id", required=True)
+    lwait_p.add_argument("--timeout-ms", type=int, default=45_000)
+    lwait_p.add_argument("--poll-ms", type=int, default=500)
+
     # Fase E.5 — quarantine ops surfaced via Desktop Guardian Proposals panel.
     quarantine_parser = sub.add_parser("quarantine", help="Quarantine proposals (Fase E.5 Desktop UI)")
     quarantine_sub = quarantine_parser.add_subparsers(dest="quarantine_command")
@@ -3370,6 +3378,23 @@ def main():
             if status == "retryable_error":
                 return 2
             return 3
+        if args.lifecycle_command == "wait-for-diary":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_wait_for_diary(
+                event_id=args.event_id,
+                timeout_ms=args.timeout_ms,
+                poll_ms=args.poll_ms,
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            if status == "ok":
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
         lifecycle_parser.print_help()
         return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):

package/src/lifecycle_events.py

@@ -51,6 +51,7 @@ Actions that carry a canonical plan: ``close``, ``delete``, ``archive``,
 from __future__ import annotations
 
 import json
+import time
 from typing import Any, Dict, Optional
 
 from db import get_db
@@ -83,24 +84,102 @@ def _normalise_payload(obj: Any) -> str:
         return "{}"
 
 
-def _session_diary_since(conn, session_id: str, dispatched_at: Optional[str]) -> bool:
-    """True if session_diary has a row for ``session_id`` created after
-    ``dispatched_at``. Used by the canonical-authority idempotency
-    guard: if the live session already produced a diary since the
-    plan was handed out, we must NOT re-dispatch it.
-    """
-    if not session_id or not dispatched_at:
-        return False
+def _max_session_diary_id(conn, session_id: str) -> int:
+    if not session_id:
+        return 0
     try:
         row = conn.execute(
-            "SELECT 1 FROM session_diary "
-            "WHERE session_id = ? AND created_at > ? LIMIT 1",
-            (str(session_id), str(dispatched_at)),
+            "SELECT COALESCE(MAX(id), 0) FROM session_diary WHERE session_id = ?",
+            (str(session_id),),
         ).fetchone()
+    except Exception:
+        return 0
+    try:
+        return int(row[0] or 0) if row else 0
+    except Exception:
+        return 0
+
+
+def _diary_checkpoint_from_actions_json(actions_json: Optional[str]) -> int:
+    if not actions_json:
+        return 0
+    try:
+        actions = json.loads(actions_json)
+    except Exception:
+        return 0
+    if not isinstance(actions, list):
+        return 0
+    for action in actions:
+        if not isinstance(action, dict):
+            continue
+        action_type = action.get("type") or action.get("kind")
+        if action_type != "wait_for_diary_write":
+            continue
+        payload = action.get("payload") if isinstance(action.get("payload"), dict) else {}
+        raw = payload.get("after_session_diary_id", action.get("after_session_diary_id", 0))
+        try:
+            return int(raw or 0)
+        except Exception:
+            return 0
+    return 0
+
+
+def _attach_diary_checkpoint(plan: Dict[str, Any], checkpoint_id: int) -> Dict[str, Any]:
+    """Store the session_diary high-water mark inside the persisted plan.
+
+    ``created_at`` only has second precision in old installs. The
+    checkpoint makes diary confirmation robust even when dispatch and
+    diary write happen in the same second.
+    """
+    actions = []
+    for action in list((plan or {}).get("canonical_actions") or []):
+        item = dict(action or {})
+        action_type = item.get("type") or item.get("kind")
+        if action_type == "wait_for_diary_write":
+            payload = dict(item.get("payload") or {})
+            payload["after_session_diary_id"] = int(checkpoint_id or 0)
+            item["payload"] = payload
+            item["after_session_diary_id"] = int(checkpoint_id or 0)
+        actions.append(item)
+    updated = dict(plan or {})
+    updated["canonical_actions"] = actions
+    return updated
+
+
+def _session_diary_evidence(
+    conn,
+    session_id: str,
+    dispatched_at: Optional[str],
+    actions_json: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Return the concrete session_diary row that satisfies a plan."""
+    if not session_id or not dispatched_at:
+        return None
+    checkpoint_id = _diary_checkpoint_from_actions_json(actions_json)
+    try:
+        if checkpoint_id > 0:
+            row = conn.execute(
+                "SELECT id, created_at FROM session_diary "
+                "WHERE session_id = ? AND id > ? ORDER BY id ASC LIMIT 1",
+                (str(session_id), int(checkpoint_id)),
+            ).fetchone()
+        else:
+            row = conn.execute(
+                "SELECT id, created_at FROM session_diary "
+                "WHERE session_id = ? AND created_at >= ? ORDER BY created_at ASC, id ASC LIMIT 1",
+                (str(session_id), str(dispatched_at)),
+            ).fetchone()
     except Exception:
         # Missing table on a minimal test harness — treat as "no diary".
-        return False
-    return row is not None
+        return None
+    if row is None:
+        return None
+    return {"session_diary_id": row[0], "created_at": row[1]}
+
+
+def _session_diary_since(conn, session_id: str, dispatched_at: Optional[str], actions_json: Optional[str] = None) -> bool:
+    """True if session_diary has evidence satisfying the canonical plan."""
+    return _session_diary_evidence(conn, session_id, dispatched_at, actions_json) is not None
 
 
 def record_lifecycle_event(
@@ -145,6 +224,8 @@ def record_lifecycle_event(
         session_id=str(session_id) if session_id else None,
         payload_snapshot=payload_snapshot or {},
     )
+    if plan is not None and session_id:
+        plan = _attach_diary_checkpoint(plan, _max_session_diary_id(conn, str(session_id)))
 
     if existing is not None:
         status = str(existing[0] or "")
@@ -171,7 +252,12 @@ def record_lifecycle_event(
         # the intent has already been satisfied by the model and we
         # must NOT ask Desktop to re-run the plan.
         if prior_plan_id and prior_dispatched_at and not prior_done_at:
-            if session_id and _session_diary_since(conn, str(session_id), str(prior_dispatched_at)):
+            if session_id and _session_diary_since(
+                conn,
+                str(session_id),
+                str(prior_dispatched_at),
+                str(prior_actions_json or ""),
+            ):
                 conn.execute(
                     "UPDATE lifecycle_events "
                     "SET delivery_status = 'already_processed', "
@@ -340,7 +426,8 @@ def record_complete_canonical(
 
     conn = get_db()
     row = conn.execute(
-        "SELECT delivery_status, canonical_plan_id, canonical_done_at "
+        "SELECT delivery_status, canonical_plan_id, canonical_done_at, "
+        "action, session_id, canonical_dispatched_at, canonical_actions_json "
         "FROM lifecycle_events WHERE event_id = ?",
         (str(event_id),),
     ).fetchone()
@@ -349,6 +436,10 @@ def record_complete_canonical(
     current_status = str(row[0] or "")
     expected_plan = row[1]
     already_done_at = row[2]
+    action = str(row[3] or "")
+    session_id = str(row[4] or "")
+    dispatched_at = row[5]
+    actions_json = row[6]
 
     if expected_plan and canonical_plan_id != expected_plan:
         return {
@@ -369,18 +460,27 @@ def record_complete_canonical(
         str((r or {}).get("status", "")).lower() not in {"ok", "success", "already_processed"}
         for r in results_list
     )
-    effective = "retryable_error" if any_failure else "canonical_done"
+    diary_evidence = _session_diary_evidence(conn, session_id, dispatched_at, actions_json)
+    diary_required = action in _DIARY_TRIGGERING and bool(session_id)
+    diary_missing = diary_required and diary_evidence is None
+    effective = "retryable_error" if (any_failure or diary_missing) else "canonical_done"
+    last_error = None
+    if any_failure:
+        last_error = "one-or-more-actions-failed"
+    elif diary_missing:
+        last_error = "canonical-diary-not-confirmed"
     conn.execute(
         "UPDATE lifecycle_events "
         "SET delivery_status = ?, "
-        "    canonical_done_at = datetime('now'), "
+        "    canonical_done_at = CASE WHEN ? = 'canonical_done' THEN datetime('now') ELSE NULL END, "
         "    canonical_done_results = ?, "
         "    last_error = ? "
         "WHERE event_id = ?",
         (
+            effective,
             effective,
             json.dumps(results_list, ensure_ascii=False),
-            "one-or-more-actions-failed" if any_failure else None,
+            last_error,
             str(event_id),
         ),
     )
@@ -390,9 +490,58 @@ def record_complete_canonical(
         "event_id": event_id,
         "canonical_plan_id": canonical_plan_id,
         "failed_actions": any_failure,
+        "diary_confirmed": diary_evidence is not None,
+        "diary_required": diary_required,
+        "session_diary_id": diary_evidence.get("session_diary_id") if diary_evidence else None,
+        "reason": "canonical-diary-not-confirmed" if diary_missing else None,
     }
 
 
+def wait_for_canonical_diary(
+    event_id: str,
+    timeout_ms: int = 45_000,
+    poll_ms: int = 500,
+) -> Dict[str, Any]:
+    """Poll until the lifecycle event has concrete session_diary evidence."""
+    if not event_id:
+        return {"status": "rejected", "reason": "missing-event-id"}
+    timeout_s = max(0.0, float(timeout_ms or 0) / 1000.0)
+    poll_s = max(0.05, float(poll_ms or 500) / 1000.0)
+    deadline = time.monotonic() + timeout_s
+    last_error: Optional[str] = None
+
+    while True:
+        conn = get_db()
+        row = conn.execute(
+            "SELECT session_id, canonical_dispatched_at, canonical_actions_json "
+            "FROM lifecycle_events WHERE event_id = ?",
+            (str(event_id),),
+        ).fetchone()
+        if row is None:
+            return {"status": "rejected", "reason": "unknown-event-id", "event_id": event_id}
+        session_id = str(row[0] or "")
+        if not session_id:
+            return {"status": "rejected", "reason": "missing-session-id", "event_id": event_id}
+        evidence = _session_diary_evidence(conn, session_id, row[1], row[2])
+        if evidence is not None:
+            return {
+                "status": "ok",
+                "event_id": event_id,
+                "session_id": session_id,
+                "diary_confirmed": True,
+                **evidence,
+            }
+        if time.monotonic() >= deadline:
+            return {
+                "status": "retryable_error",
+                "event_id": event_id,
+                "session_id": session_id,
+                "diary_confirmed": False,
+                "reason": last_error or "diary-confirm-timeout",
+            }
+        time.sleep(min(poll_s, max(0.0, deadline - time.monotonic())))
+
+
 def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
     if not event_id:
         return None

package/src/lifecycle_prompts.py

@@ -19,7 +19,7 @@ import json
 from typing import Any, Dict, List, Optional
 
 
-PLAN_VERSION = 1
+PLAN_VERSION = 3
 
 
 # Actions that trigger a canonical diary+stop plan. `switch` and
@@ -34,7 +34,8 @@ DIARY_TRIGGERING_ACTIONS = {"close", "delete", "archive", "app-exit"}
 # executes each action; on timeout it reports status=failed and Brain
 # flips delivery_status to retryable_error.
 DEFAULT_RESUME_TIMEOUT_MS = 2_000
-DEFAULT_INJECT_TIMEOUT_MS = 6_000
+DEFAULT_INJECT_TIMEOUT_MS = 30_000
+DEFAULT_DIARY_WAIT_TIMEOUT_MS = 45_000
 DEFAULT_STOP_TIMEOUT_MS = 3_000
 
 
@@ -79,6 +80,27 @@ def _diary_prompt_for_action(
     )
 
 
+def _canonical_action(
+    action_id: str,
+    action_type: str,
+    session_id: str,
+    timeout_ms: int,
+    **extra: Any,
+) -> Dict[str, Any]:
+    """Build one Desktop action with the v2 shape plus one-release mirrors."""
+    action: Dict[str, Any] = {
+        "id": action_id,
+        "type": action_type,
+        # Compatibility mirror for Desktop <= 0.28.1. Remove after one
+        # release once every supported Desktop consumes `type`.
+        "kind": action_type,
+        "session_id": str(session_id),
+        "timeout_ms": timeout_ms,
+    }
+    action.update(extra)
+    return action
+
+
 def build_canonical_plan(
     event_id: str,
     action: str,
@@ -106,26 +128,28 @@ def build_canonical_plan(
     prompt = _diary_prompt_for_action(action, conversation_id, payload_snapshot)
 
     actions: List[Dict[str, Any]] = [
-        {
-            "id": "a1",
-            "kind": "resume_session",
-            "session_id": str(session_id),
-            "timeout_ms": DEFAULT_RESUME_TIMEOUT_MS,
-        },
-        {
-            "id": "a2",
-            "kind": "inject_prompt",
-            "session_id": str(session_id),
-            "prompt": prompt,
-            "expected_tool_call": "nexo_session_diary_write",
-            "timeout_ms": DEFAULT_INJECT_TIMEOUT_MS,
-        },
-        {
-            "id": "a3",
-            "kind": "stop_session",
-            "session_id": str(session_id),
-            "timeout_ms": DEFAULT_STOP_TIMEOUT_MS,
-        },
+        _canonical_action("a1", "resume_session", str(session_id), DEFAULT_RESUME_TIMEOUT_MS),
+        _canonical_action(
+            "a2",
+            "inject_prompt",
+            str(session_id),
+            DEFAULT_INJECT_TIMEOUT_MS,
+            payload={"prompt": prompt},
+            # Compatibility mirror for Desktop <= 0.28.1. Remove after one
+            # release once every supported Desktop consumes `payload.prompt`.
+            prompt=prompt,
+            expected_tool_call="nexo_session_diary_write",
+        ),
+        _canonical_action(
+            "a3",
+            "wait_for_diary_write",
+            str(session_id),
+            DEFAULT_DIARY_WAIT_TIMEOUT_MS,
+            event_id=str(event_id),
+            expected_tool_call="nexo_session_diary_write",
+            evidence="session_diary",
+        ),
+        _canonical_action("a4", "stop_session", str(session_id), DEFAULT_STOP_TIMEOUT_MS),
     ]
     return {
         "canonical_plan_id": canonical_plan_id(event_id, PLAN_VERSION),

package/src/model_warmup.py

@@ -0,0 +1,177 @@
+"""Predownload the local models used by NEXO Brain/Desktop flows.
+
+The installer invokes this script after Python dependencies are present.
+``--dry-run`` is intentionally dependency-free so package tests can verify the
+contract without downloading 1+ GB of weights.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+SRC_DIR = Path(__file__).resolve().parent
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+
+@dataclass(frozen=True)
+class WarmupTarget:
+    name: str
+    kind: str
+    model_id: str
+    source: str
+    revision: str | None = None
+    required: bool = True
+
+
+def warmup_targets() -> list[WarmupTarget]:
+    from classifier_local import MODEL_ID, MODEL_REVISION
+
+    return [
+        WarmupTarget(
+            name="local-zero-shot-classifier",
+            kind="transformers_sequence_classifier",
+            model_id=MODEL_ID,
+            revision=MODEL_REVISION,
+            source="src/classifier_local.py",
+        ),
+        WarmupTarget(
+            name="bge-base-embeddings",
+            kind="fastembed_embedding",
+            model_id="BAAI/bge-base-en-v1.5",
+            source="src/cognitive/_core.py",
+        ),
+        WarmupTarget(
+            name="bge-small-embeddings",
+            kind="fastembed_embedding",
+            model_id="BAAI/bge-small-en-v1.5",
+            source="src/migrate_embeddings.py",
+        ),
+        WarmupTarget(
+            name="cross-encoder-reranker",
+            kind="fastembed_reranker",
+            model_id="Xenova/ms-marco-MiniLM-L-6-v2",
+            source="src/cognitive/_core.py",
+        ),
+    ]
+
+
+def _state_path() -> Path:
+    nexo_home = Path(os.environ.get("NEXO_HOME", "~/.nexo")).expanduser()
+    return nexo_home / "runtime" / "operations" / "model-warmup-state.json"
+
+
+def _write_state(payload: dict[str, Any]) -> None:
+    path = _state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def _warm_transformers(target: WarmupTarget) -> None:
+    from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+    kwargs: dict[str, str] = {}
+    if target.revision:
+        kwargs["revision"] = target.revision
+    AutoTokenizer.from_pretrained(target.model_id, **kwargs)
+    AutoModelForSequenceClassification.from_pretrained(target.model_id, **kwargs)
+
+
+def _warm_fastembed_embedding(target: WarmupTarget) -> None:
+    from fastembed import TextEmbedding
+
+    model = TextEmbedding(target.model_id)
+    list(model.embed(["NEXO model warmup"]))
+
+
+def _warm_fastembed_reranker(target: WarmupTarget) -> None:
+    from fastembed.rerank.cross_encoder import TextCrossEncoder
+
+    TextCrossEncoder(target.model_id)
+
+
+def warm_target(target: WarmupTarget) -> None:
+    if target.kind == "transformers_sequence_classifier":
+        _warm_transformers(target)
+        return
+    if target.kind == "fastembed_embedding":
+        _warm_fastembed_embedding(target)
+        return
+    if target.kind == "fastembed_reranker":
+        _warm_fastembed_reranker(target)
+        return
+    raise ValueError(f"unknown warmup target kind: {target.kind}")
+
+
+def target_to_json(target: WarmupTarget) -> dict[str, Any]:
+    return {key: value for key, value in asdict(target).items() if value is not None}
+
+
+def run(args: argparse.Namespace) -> int:
+    targets = warmup_targets()
+    if args.dry_run:
+        payload = {
+            "ok": True,
+            "dry_run": True,
+            "targets": [target_to_json(target) for target in targets],
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+        else:
+            for target in targets:
+                revision = f"@{target.revision}" if target.revision else ""
+                print(f"{target.name}: {target.model_id}{revision}")
+        return 0
+
+    started = time.time()
+    results: list[dict[str, Any]] = []
+    ok = True
+    for target in targets:
+        item = target_to_json(target)
+        item["started_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        try:
+            if not args.json:
+                revision = f"@{target.revision}" if target.revision else ""
+                print(f"[model-warmup] {target.name}: {target.model_id}{revision}", flush=True)
+            warm_target(target)
+            item["ok"] = True
+        except Exception as exc:  # pragma: no cover - depends on host/network/cache
+            item["ok"] = False
+            item["error"] = str(exc)
+            if target.required:
+                ok = False
+            if not args.json:
+                print(f"[model-warmup] FAILED {target.name}: {exc}", file=sys.stderr, flush=True)
+        item["finished_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        results.append(item)
+
+    payload = {
+        "ok": ok,
+        "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(started)),
+        "finished_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "targets": results,
+    }
+    _write_state(payload)
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    return 0 if ok or not args.strict else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Predownload NEXO local model weights.")
+    parser.add_argument("--dry-run", action="store_true", help="List model targets without importing ML dependencies.")
+    parser.add_argument("--json", action="store_true", help="Print JSON output.")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero if any required model fails.")
+    return run(parser.parse_args())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/plugins/lifecycle_events.py

@@ -147,6 +147,27 @@ def handle_nexo_lifecycle_complete_canonical(
     return json.dumps(ack, ensure_ascii=False)
 
 
+def handle_nexo_lifecycle_wait_for_diary(
+    event_id: str,
+    timeout_ms: int = 45_000,
+    poll_ms: int = 500,
+) -> str:
+    """Wait until a canonical lifecycle event has real diary evidence."""
+    try:
+        ack = lifecycle_events.wait_for_canonical_diary(
+            event_id=str(event_id or ""),
+            timeout_ms=int(timeout_ms or 0),
+            poll_ms=int(poll_ms or 500),
+        )
+    except Exception as exc:
+        return json.dumps({
+            "status": "retryable_error",
+            "reason": f"{type(exc).__name__}: {exc}",
+            "handler_threw": True,
+        }, ensure_ascii=False)
+    return json.dumps(ack, ensure_ascii=False)
+
+
 TOOLS = [
     (
         handle_nexo_lifecycle_event,
@@ -163,4 +184,9 @@ TOOLS = [
         "nexo_lifecycle_complete_canonical",
         "Confirm that Desktop finished executing the canonical_actions Brain handed out in a prior nexo_lifecycle_event call. Brain marks canonical_done_at only on this confirmation.",
     ),
+    (
+        handle_nexo_lifecycle_wait_for_diary,
+        "nexo_lifecycle_wait_for_diary",
+        "Wait for concrete session_diary evidence for a canonical lifecycle event before Desktop stops the session.",
+    ),
 ]

package/templates/CLAUDE.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-claude-md-version: 2.1.5 -->
+<!-- nexo-claude-md-version: 2.1.6 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
@@ -20,6 +20,16 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 **Presentation:** {{NAME}} speaks first. Conversational greeting adapted to time of day. Tell what you HAVE DONE, not list pending items. Menu only if the user asks.
 <!-- nexo:end:startup -->
 
+<!-- nexo:start:tools_at_startup -->
+## Tools availability at startup
+Claude Code may list `mcp__nexo__*` tools as **deferred** at session start (name surfaced, schema not yet loaded). Deferred ≠ unavailable.
+
+- If a needed `mcp__nexo__*` tool is not directly callable, run `ToolSearch` with `select:mcp__nexo__<name>[,<name>...]` to load its schema — BEFORE reporting a blocked session or missing capability.
+- If `nexo_startup` itself appears deferred, load it via ToolSearch first — never start a session without a real SID.
+- If ToolSearch still cannot resolve a `nexo_*` tool, then (and only then) treat it as a real runtime gap and surface it as a blocker.
+- Diagnostic plane: `nexo_doctor plane='installation_live'` inspects client/install surfaces — consult it when tools appear missing on a fresh install.
+<!-- nexo:end:tools_at_startup -->
+
 ## Protocol (6 rules)
 1. `nexo_startup` once per session and keep the returned `SID`.
 2. `nexo_heartbeat` on every user message.

package/templates/CODEX.AGENTS.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-codex-agents-version: 1.2.4 -->
+<!-- nexo-codex-agents-version: 1.2.5 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — NEXO Shared Brain for Codex
@@ -17,6 +17,14 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 4. Execute overdue followups silently when appropriate.
 5. Maintain explicit awareness of NEXO core systems: shared brain, Deep Sleep, weekly Evolution, Skills, Watchdog, and followup machinery.
 
+## Tools availability at startup
+Codex (and Claude Code) may list `mcp__nexo__*` tools as **deferred** at session start (name surfaced, schema not yet loaded). Deferred ≠ unavailable.
+
+- If a needed `mcp__nexo__*` tool is not directly callable, resolve its schema via the client's tool-discovery path (Claude Code: `ToolSearch` with `select:mcp__nexo__<name>`) BEFORE reporting a blocked session or missing capability.
+- If `nexo_startup` itself appears deferred, load it first — never start a session without a real SID.
+- If discovery still cannot resolve a `nexo_*` tool, then (and only then) treat it as a real runtime gap and surface it as a blocker.
+- Diagnostic plane: `nexo_doctor plane='installation_live'` inspects client/install surfaces — consult it when tools appear missing on a fresh install.
+
 ## Protocol (6 rules)
 1. `nexo_startup` once per session, then keep the returned `SID`.
 2. `nexo_heartbeat` on every user message.

package/tool-enforcement-map.json

@@ -1882,6 +1882,19 @@
       },
       "triggers_after": []
     },
+    "nexo_lifecycle_wait_for_diary": {
+      "description": "Wait for real session_diary evidence for a canonical lifecycle event before stop_session is allowed.",
+      "category": "lifecycle",
+      "source": "plugin:lifecycle_events",
+      "requires": [],
+      "provides": [],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_media_memory_add": {
       "description": "Store non-text artifact metadata",
       "category": "media",