nexo-brain 7.12.2 → 7.12.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.12.2",
+  "version": "7.12.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/bin/nexo-brain.js

@@ -111,6 +111,10 @@ const DEFAULT_CLAUDE_CODE_REASONING_EFFORT = _MODEL_DEFAULTS.claude_code.reasoni
 const DEFAULT_CODEX_MODEL = _MODEL_DEFAULTS.codex.model;
 const DEFAULT_CODEX_REASONING_EFFORT = _MODEL_DEFAULTS.codex.reasoning_effort || "";
 
+function isDesktopManagedInstall() {
+  return String(process.env.NEXO_DESKTOP_MANAGED || "").trim() === "1";
+}
+
 // v6.0.0 — Hook manifest is the single source of truth for which hook
 // handlers get registered. Both plugin mode (hooks/hooks.json) and npm
 // mode (this installer's registerAllCoreHooks) read from the same file.
@@ -223,6 +227,62 @@ function run(cmd, opts = {}) {
 
 function log(msg) {
   console.log(`  ${msg}`);
+  try {
+    const logPath = path.join(
+      NEXO_HOME,
+      "runtime",
+      "bootstrap",
+      "logs",
+      "brain-install.log"
+    );
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, `[${new Date().toISOString()}] ${msg}\n`);
+  } catch {}
+}
+
+let _stagedRuntimeBundleRoot = null;
+let _stagedRuntimeCleanup = null;
+
+function getRuntimeBundleRoot() {
+  if (_stagedRuntimeBundleRoot) {
+    return _stagedRuntimeBundleRoot;
+  }
+  const bundleRoot = path.resolve(__dirname, "..");
+  if (process.platform !== "linux") {
+    return bundleRoot;
+  }
+  const normalizedRoot = bundleRoot.replace(/\\/g, "/");
+  if (!normalizedRoot.startsWith("/mnt/")) {
+    return bundleRoot;
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(require("os").tmpdir(), "nexo-brain-stage-"));
+  const stagedRoot = path.join(tmpRoot, path.basename(bundleRoot));
+  fs.mkdirSync(stagedRoot, { recursive: true });
+
+  log("Staging bundled runtime into local Linux storage...");
+  const tarCmd =
+    `tar --exclude=__pycache__ --exclude=node_modules --exclude='*.pyc' ` +
+    `--exclude='*.db' --exclude=.git ` +
+    `-C ${JSON.stringify(bundleRoot)} -cf - . | ` +
+    `tar -C ${JSON.stringify(stagedRoot)} -xf -`;
+  const stageResult = spawnSync("/bin/sh", ["-c", tarCmd], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10 * 60 * 1000,
+  });
+  if (stageResult.status !== 0) {
+    const detail = (stageResult.stderr || stageResult.stdout || "").trim() || `exit ${stageResult.status}`;
+    throw new Error(`Failed to stage bundled runtime from Windows storage: ${detail}`);
+  }
+  log(`  Runtime bundle staged at ${stagedRoot}`);
+  _stagedRuntimeBundleRoot = stagedRoot;
+  _stagedRuntimeCleanup = () => {
+    try {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {}
+  };
+  return _stagedRuntimeBundleRoot;
 }
 
 function readPackageJson() {
@@ -500,6 +560,15 @@ function runMandatoryModelWarmup(pythonPath, nexoHome = NEXO_HOME, { reason = "i
   log("Local model warmup complete.");
 }
 
+function runDesktopAwareModelWarmup(pythonPath, nexoHome = NEXO_HOME, options = {}) {
+  const reason = String((options && options.reason) || "install");
+  if (isDesktopManagedInstall()) {
+    log(`Desktop-managed runtime detected — local model warmup deferred during ${reason}.`);
+    return;
+  }
+  runMandatoryModelWarmup(pythonPath, nexoHome, options);
+}
+
 async function runWarmupModelsCommand(args) {
   const dryRun = args.includes("--dry-run");
   const json = args.includes("--json");
@@ -729,6 +798,10 @@ function resolveRuntimeSchedulePath(nexoHome) {
 
 function finalizeF06Layout(python, nexoHome = NEXO_HOME) {
   try {
+    // auto_update lives in NEXO_CODE (e.g. ~/.nexo/core or ~/.nexo/core/current),
+    // not directly in NEXO_HOME, so PYTHONPATH must point at the runtime code
+    // directory or `import auto_update` fails with ModuleNotFoundError.
+    const codeDir = runtimeCodeDir(nexoHome);
     const result = spawnSync(
       python,
       [
@@ -744,8 +817,8 @@ function finalizeF06Layout(python, nexoHome = NEXO_HOME) {
         env: {
           ...process.env,
           NEXO_HOME: nexoHome,
-          NEXO_CODE: runtimeCodeDir(nexoHome),
-          PYTHONPATH: nexoHome,
+          NEXO_CODE: codeDir,
+          PYTHONPATH: codeDir,
         },
         encoding: "utf8",
       },
@@ -1451,7 +1524,7 @@ function getDefaultSchedule(timezone) {
 }
 
 function writeDesktopProductMode(nexoHome) {
-  if (String(process.env.NEXO_DESKTOP_MANAGED || "").trim() !== "1") return;
+  if (!isDesktopManagedInstall()) return;
   const configDir = resolveRuntimeConfigDir(nexoHome);
   fs.mkdirSync(configDir, { recursive: true });
   const target = path.join(configDir, "product-mode.json");
@@ -1478,7 +1551,7 @@ function ensureEvolutionObjectiveForCurrentProductMode(nexoHome) {
   const brainDir = resolveRuntimeBrainDir(nexoHome);
   fs.mkdirSync(brainDir, { recursive: true });
   const evoObjectivePath = path.join(brainDir, "evolution-objective.json");
-  const desktopManaged = String(process.env.NEXO_DESKTOP_MANAGED || "").trim() === "1";
+  const desktopManaged = isDesktopManagedInstall();
   let payload = null;
   if (fs.existsSync(evoObjectivePath)) {
     try {
@@ -1801,6 +1874,29 @@ function installClaudeCodeCli(platform) {
   const desktopNode = String(process.env.NEXO_DESKTOP_NODE || "").trim();
   const bundledNpmCli = String(process.env.NEXO_DESKTOP_NPM_CLI || "").trim();
   const managedPrefix = managedClaudePrefix();
+  const desktopManaged = isDesktopManagedInstall();
+
+  // OFFLINE-FIRST: detect bundled claude-code .tgz and install from it.
+  // Path: resources/brain-bundle/claude-code/claude-code-X.Y.Z.tgz (relative
+  // to bin/, so __dirname/../claude-code/). Falls back to PyPI/npm if absent.
+  const bundledClaudeDir = path.join(__dirname, "..", "claude-code");
+  if (fs.existsSync(bundledClaudeDir)) {
+    const tgzFiles = fs.readdirSync(bundledClaudeDir).filter((f) => f.endsWith(".tgz"));
+    if (tgzFiles.length > 0) {
+      const tgzPath = path.join(bundledClaudeDir, tgzFiles[0]);
+      log("  Installing claude-code from bundled tarball (offline)...");
+      spawnSync(
+        "npm",
+        ["install", "-g", "--prefix", managedPrefix, tgzPath],
+        { stdio: "inherit", env: installEnv },
+      );
+      claudeInstalled = detectInstalledClients().claude_code.path || "";
+      if (claudeInstalled) {
+        persistClaudeCliPath(claudeInstalled);
+        return { installed: true, path: claudeInstalled };
+      }
+    }
+  }
 
   if (desktopNode && bundledNpmCli) {
     spawnSync(
@@ -1818,6 +1914,23 @@ function installClaudeCodeCli(platform) {
     }
   }
 
+  if (desktopManaged) {
+    spawnSync(
+      "npm",
+      ["install", "-g", "--prefix", managedPrefix, "@anthropic-ai/claude-code"],
+      {
+        stdio: "inherit",
+        env: installEnv,
+      },
+    );
+    claudeInstalled = detectInstalledClients().claude_code.path || "";
+    if (claudeInstalled) {
+      persistClaudeCliPath(claudeInstalled);
+      return { installed: true, path: claudeInstalled };
+    }
+    return { installed: false, path: "" };
+  }
+
   spawnSync("npx", ["-y", "@anthropic-ai/claude-code", "--version"], {
     stdio: "pipe",
     timeout: 60000,
@@ -1847,6 +1960,7 @@ function installCodexCli() {
 async function configureClientSetup({ lang, useDefaults, autoInstall, detected }) {
   const strings = clientSetupStrings(lang);
   const setup = defaultClientSetup(detected);
+  const desktopManaged = String(process.env.NEXO_DESKTOP_MANAGED || "").trim() === "1";
   setup.client_install_preferences = {
     claude_code: autoInstall === "auto" ? "auto" : "ask",
     codex: autoInstall === "auto" ? "auto" : "ask",
@@ -1898,6 +2012,20 @@ async function configureClientSetup({ lang, useDefaults, autoInstall, detected }
   const required = requiredCliClients(setup);
   for (const client of required) {
     if (detected[client] && detected[client].installed) continue;
+    if (desktopManaged && client === "claude_code") {
+      const bundledClaudeDir = path.join(__dirname, "..", "claude-code");
+      let hasBundle = false;
+      try {
+        if (fs.existsSync(bundledClaudeDir)) {
+          hasBundle = fs.readdirSync(bundledClaudeDir).some((f) => f.endsWith(".tgz"));
+        }
+      } catch (_) {}
+      if (!hasBundle) {
+        log("Claude Code install deferred to Desktop final sync.");
+        continue;
+      }
+      log("Bundled Claude Code tarball detected — installing offline now.");
+    }
     let shouldInstall = useDefaults || autoInstall === "auto";
     if (!shouldInstall && process.stdin.isTTY && process.stdout.isTTY) {
       const question = client === "claude_code" ? strings.installClaudeQ : strings.installCodexQ;
@@ -1926,6 +2054,10 @@ async function configureClientSetup({ lang, useDefaults, autoInstall, detected }
   }
 
   if (setup.automation_enabled && setup.automation_backend !== "none" && !detected[setup.automation_backend]?.installed) {
+    if (desktopManaged && setup.automation_backend === "claude_code") {
+      log("Claude Code will be provisioned by Desktop after the core runtime is ready.");
+      return { setup, detected };
+    }
     const label = setup.automation_backend === "claude_code" ? "Claude Code" : "Codex";
     log(strings.automationDisabled(label));
     setup.automation_enabled = false;
@@ -2448,6 +2580,15 @@ async function runSetup() {
     process.exit(1);
   }
 
+  const bundleRoot = getRuntimeBundleRoot();
+  const bundleSrcDir = path.join(bundleRoot, "src");
+  const bundleTemplatesDir = path.join(bundleRoot, "templates");
+  process.on("exit", () => {
+    if (_stagedRuntimeCleanup) {
+      _stagedRuntimeCleanup();
+    }
+  });
+
   const onboardingMigration = ensureOnboardingCompletionMarker(NEXO_HOME);
   if (onboardingMigration.changed) {
     log("Migrated legacy calibration completion marker.");
@@ -2479,7 +2620,7 @@ async function runSetup() {
         }
 
         // Recursive copy helper (skips __pycache__, .pyc, .db files)
-        const srcDir = path.join(__dirname, "..", "src");
+        const srcDir = bundleSrcDir;
         const copyDirRec = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
           fs.readdirSync(src).forEach(item => {
@@ -2552,7 +2693,7 @@ async function runSetup() {
         }
 
         const migPythonForWarmup = findVenvPython(NEXO_HOME) || "python3";
-        runMandatoryModelWarmup(migPythonForWarmup, NEXO_HOME, { reason: "update", installRuntimeDeps: false });
+        runDesktopAwareModelWarmup(migPythonForWarmup, NEXO_HOME, { reason: "update", installRuntimeDeps: false });
 
         // Update plugins (all .py files in plugins/)
         const pluginsSrc = path.join(srcDir, "plugins");
@@ -2607,7 +2748,7 @@ async function runSetup() {
         // hand-edited template under ~/.nexo/templates/ is replaced on
         // upgrade. Keep local forks under personal/ or outside the runtime
         // home to avoid silent loss.
-        const migTemplatesSrc = path.join(__dirname, "..", "templates");
+        const migTemplatesSrc = bundleTemplatesDir;
         const migTemplatesDest = path.join(NEXO_HOME, "templates");
         if (fs.existsSync(migTemplatesSrc)) {
           copyDirRec(migTemplatesSrc, migTemplatesDest);
@@ -2656,7 +2797,7 @@ async function runSetup() {
             ? { runtime_repaired_from: activeRuntimeVersion }
             : {}),
         }, null, 2));
-        syncRuntimePackageMetadata(path.join(__dirname, ".."), NEXO_HOME);
+        syncRuntimePackageMetadata(bundleRoot, NEXO_HOME);
         log("Finalizing F0.6 runtime layout...");
         const migLayoutFinalize = finalizeF06Layout(migPython, NEXO_HOME);
         if (!migLayoutFinalize.ok) {
@@ -2670,7 +2811,7 @@ async function runSetup() {
 
         // Keep the rendered template in-memory for version tracking, but do
         // not drop a loose reference file in NEXO_HOME root.
-        const templateSrc = path.join(__dirname, "..", "templates", "CLAUDE.md.template");
+        const templateSrc = path.join(bundleTemplatesDir, "CLAUDE.md.template");
         if (fs.existsSync(templateSrc)) {
           const operatorName = installed.operator_name || DEFAULT_ASSISTANT_NAME;
           let claudeMd = fs.readFileSync(templateSrc, "utf8")
@@ -2742,7 +2883,7 @@ async function runSetup() {
       // 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");
+      const cronsSrc = path.join(bundleSrcDir, "crons");
       if (fs.existsSync(cronsSrc)) {
         const copyDirRec2 = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
@@ -2767,7 +2908,7 @@ async function runSetup() {
 
       // Same version — refresh packaged core skills/templates/runtime helpers too.
       const skillsCoreDest = path.join(NEXO_HOME, "core", "skills");
-      const skillsCoreSrc = path.join(__dirname, "..", "src", "skills");
+      const skillsCoreSrc = path.join(bundleSrcDir, "skills");
       if (fs.existsSync(skillsCoreSrc)) {
         const copyDirRec3 = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
@@ -2784,16 +2925,16 @@ async function runSetup() {
       }
 
       ["skills_runtime.py"].forEach((fname) => {
-        const srcFile = path.join(__dirname, "..", "src", fname);
+        const srcFile = path.join(bundleSrcDir, fname);
         const destFile = path.join(NEXO_HOME, "core", fname);
         if (fs.existsSync(srcFile)) {
           fs.mkdirSync(path.dirname(destFile), { recursive: true });
           fs.copyFileSync(srcFile, destFile);
         }
       });
-      syncRuntimePackageMetadata(path.join(__dirname, ".."), NEXO_HOME);
+      syncRuntimePackageMetadata(bundleRoot, NEXO_HOME);
 
-      const templatesSrc = path.join(__dirname, "..", "templates");
+      const templatesSrc = bundleTemplatesDir;
       const templatesDest = path.join(NEXO_HOME, "templates");
       if (fs.existsSync(templatesSrc)) {
         fs.mkdirSync(templatesDest, { recursive: true });
@@ -2821,10 +2962,26 @@ async function runSetup() {
         throw new Error(`F0.6 layout finalization failed: ${syncLayoutFinalize.error}`);
       }
 
-      runMandatoryModelWarmup(syncPython, NEXO_HOME, { reason: "repair" });
+      runDesktopAwareModelWarmup(syncPython, NEXO_HOME, { reason: "repair" });
       logMacPermissionsNotice(NEXO_HOME, syncPython);
 
       log(`Already at v${currentVersion}. No migration needed.`);
+
+      // Ensure bundled Claude Code is installed even when migration is skipped.
+      try {
+        const _claudeCheck = detectInstalledClients().claude_code;
+        if (!_claudeCheck.installed) {
+          const _bundledClaudeDir = path.join(__dirname, "..", "claude-code");
+          if (fs.existsSync(_bundledClaudeDir)) {
+            const _tgzFiles = fs.readdirSync(_bundledClaudeDir).filter((f) => f.endsWith(".tgz"));
+            if (_tgzFiles.length > 0) {
+              log("Bundled Claude Code tarball detected after migration-skip — installing offline.");
+              installClaudeCodeCli(process.platform);
+            }
+          }
+        }
+      } catch (_e) {}
+
       closeReadline();
       return;
     } catch (e) {
@@ -3316,11 +3473,22 @@ async function runSetup() {
   // Use venv python if available, otherwise fall back to system python with --break-system-packages
   const pipPython = fs.existsSync(venvPython) ? venvPython : python;
   const requirementsFile = path.join(__dirname, "..", "src", "requirements.txt");
-  const pipArgs = ["-m", "pip", "install", "--quiet", "-r", requirementsFile];
+  // Detect bundled wheels in resources/python-wheels (offline-first). If
+  // present, pip uses --no-index --find-links to install without internet.
+  // Falls back to PyPI if bundle not found.
+  const bundledWheelsDir = path.join(__dirname, "..", "python-wheels");
+  const useBundle = fs.existsSync(bundledWheelsDir);
+  const pipArgs = useBundle
+    ? ["-m", "pip", "install", "--no-index", "--find-links", bundledWheelsDir, "--progress-bar", "off", "-r", requirementsFile]
+    : ["-m", "pip", "install", "-v", "--progress-bar", "off", "--default-timeout=60", "-r", requirementsFile];
   if (!fs.existsSync(venvPython)) {
-    pipArgs.push("--break-system-packages");  // Fallback for systems without venv
+    pipArgs.push("--break-system-packages");
+  }
+  if (useBundle) {
+    log("  Installing Python deps from bundled wheels (offline)...");
+  } else {
+    log("  Installing Python deps from PyPI (online)...");
   }
-
   const pipInstall = spawnSync(pipPython, pipArgs, { stdio: "inherit" });
   if (pipInstall.status !== 0) {
     log("Failed to install Python dependencies.");
@@ -3332,7 +3500,54 @@ async function runSetup() {
     python = venvPython;
   }
   log("Dependencies installed.");
-  runMandatoryModelWarmup(python, NEXO_HOME, { reason: "install", installRuntimeDeps: false });
+
+  // OFFLINE-FIRST: copy bundled LLM models to runtime/models BEFORE warmup,
+  // so fastembed finds them locally and skips the ~217MB HuggingFace download.
+  // Bundle layout: resources/brain-bundle/models/<source-repo-name>/<all files>.
+  // Target layout: <NEXO_HOME>/runtime/models/<spec.name slugified>/<revision>/<files>.
+  // We map by source_repo basename to match local_model_manifest.json.
+  const bundledModelsDir = path.join(__dirname, "..", "models");
+  if (fs.existsSync(bundledModelsDir)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "src", "local_model_manifest.json"), "utf8"));
+      const runtimeModelsDir = path.join(NEXO_HOME, "runtime", "models");
+      let modelsCopied = 0;
+      for (const spec of manifest.models || []) {
+        // Bundle layout supports either model_id basename (e.g.
+        // "bge-base-en-v1.5" from "BAAI/bge-base-en-v1.5") or source_repo
+        // basename (e.g. "bge-base-en-v1.5-onnx-q" from "qdrant/...").
+        const modelIdName = (spec.model_id || "").split("/").pop();
+        const sourceRepoName = (spec.source_repo || "").split("/").pop();
+        let sourceDir = path.join(bundledModelsDir, modelIdName);
+        if (!fs.existsSync(sourceDir)) {
+          sourceDir = path.join(bundledModelsDir, sourceRepoName);
+        }
+        if (!fs.existsSync(sourceDir)) continue;
+        const slug = (spec.name || "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const targetDir = path.join(runtimeModelsDir, slug, spec.revision);
+        fs.mkdirSync(targetDir, { recursive: true });
+        for (const f of (spec.required_files || [])) {
+          const src = path.join(sourceDir, f.path);
+          const dst = path.join(targetDir, f.path);
+          if (fs.existsSync(src) && !fs.existsSync(dst)) {
+            fs.copyFileSync(src, dst);
+          }
+        }
+        // Write the lock file to match revision (avoids re-download).
+        fs.writeFileSync(path.join(targetDir, ".nexo-model-lock.json"), JSON.stringify({
+          name: spec.name, kind: spec.kind, model_id: spec.model_id,
+          source_repo: spec.source_repo, revision: spec.revision, model_file: spec.model_file,
+          required_files: spec.required_files,
+        }, null, 2));
+        modelsCopied++;
+      }
+      if (modelsCopied > 0) log(`  Copied ${modelsCopied} pre-bundled LLM model(s) (offline).`);
+    } catch (err) {
+      log(`  WARN: bundled models copy failed: ${err.message}`);
+    }
+  }
+
+  runDesktopAwareModelWarmup(python, NEXO_HOME, { reason: "install", installRuntimeDeps: false });
 
   // Step 4: Create ~/.nexo/
   log("Setting up NEXO home...");
@@ -3381,15 +3596,15 @@ async function runSetup() {
       files_updated: 0,
     }, null, 2)
   );
-  syncRuntimePackageMetadata(path.join(__dirname, ".."), NEXO_HOME);
+  syncRuntimePackageMetadata(bundleRoot, NEXO_HOME);
 
   // Copy source files
   log("Copying core runtime files...");
-  const srcDir = path.join(__dirname, "..", "src");
+  const srcDir = bundleSrcDir;
   const pluginsSrcDir = path.join(srcDir, "plugins");
   const scriptsSrcDir = path.join(srcDir, "scripts");
   const skillsSrcDir = path.join(srcDir, "skills");
-  const templateDir = path.join(__dirname, "..", "templates");
+  const templateDir = bundleTemplatesDir;
 
   // Recursive copy helper (skips __pycache__, .pyc, .db files)
   const copyDirRecursive = (src, dest) => {
@@ -3407,7 +3622,7 @@ async function runSetup() {
   };
 
   // Core flat files (single .py files in src/)
-  const coreFiles = getCoreRuntimeFlatFiles();
+  const coreFiles = getCoreRuntimeFlatFiles(srcDir);
   coreFiles.forEach((f) => {
     const src = path.join(srcDir, f);
     if (fs.existsSync(src)) {
@@ -4429,6 +4644,10 @@ See ~/.nexo/ for configuration.
   console.log(`  \u255A${"═".repeat(bw - 2)}\u255D`);
   console.log("");
 
+  if (_stagedRuntimeCleanup) {
+    _stagedRuntimeCleanup();
+    _stagedRuntimeCleanup = null;
+  }
   closeReadline();
 }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "7.12.2",
+  "version": "7.12.4",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
+  "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.",
   "homepage": "https://nexo-brain.com",
   "bin": {
     "nexo-brain": "bin/nexo-brain.js",

package/src/cli.py

@@ -2518,6 +2518,7 @@ def _skills_compose(args):
 def _uninstall(args):
     """Stop all crons, remove MCP config and hooks, preserve user data."""
     from pathlib import Path
+    from windows_runtime import cleanup_windows_host_artifacts, running_inside_wsl, running_from_windows_host
 
     nexo_home = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo"))
     dry_run = args.dry_run
@@ -2566,6 +2567,20 @@ def _uninstall(args):
             if not dry_run:
                 subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
 
+        if running_inside_wsl() or running_from_windows_host():
+            host_cleanup = cleanup_windows_host_artifacts(
+                delete_data=delete_data,
+                dry_run=dry_run,
+            )
+            for action in host_cleanup.get("actions", []):
+                log_action(
+                    action.get("category", "remove-win-host-artifact"),
+                    action.get("detail", ""),
+                    action.get("path", ""),
+                )
+            for error in host_cleanup.get("errors", []):
+                errors.append(f"Windows host cleanup: {error}")
+
     # ── 2. Remove MCP server and hooks from Claude Code settings ──
     claude_settings = Path.home() / ".claude" / "settings.json"
     if claude_settings.exists():

package/src/health_check.py

@@ -25,7 +25,7 @@ import time
 from pathlib import Path
 from typing import Any
 
-from windows_runtime import running_inside_wsl, windows_runtime_status
+from windows_runtime import query_windows_host_tasks, running_inside_wsl, windows_runtime_status
 
 
 def _nexo_home() -> Path:
@@ -83,17 +83,53 @@ def _check_database() -> dict:
 
 def _check_crons() -> dict:
     out: dict[str, Any] = {}
-    # macOS LaunchAgents
-    agents_dir = Path.home() / "Library" / "LaunchAgents"
-    if agents_dir.is_dir():
+    system = platform.system()
+    release = platform.release()
+
+    if system == "Darwin":
+        agents_dir = Path.home() / "Library" / "LaunchAgents"
+        out["platform"] = "macos"
+        if agents_dir.is_dir():
+            try:
+                plists = [p for p in agents_dir.glob("com.nexo.*.plist")]
+                out["launch_agents"] = len(plists)
+            except Exception as exc:
+                out["error"] = str(exc)
+                out["status"] = "degraded"
+                return out
+        out["status"] = "ok"
+        return out
+
+    if system == "Linux":
+        unit_dir = Path.home() / ".config" / "systemd" / "user"
+        inside_wsl = running_inside_wsl(system=system, release=release)
+        out["platform"] = "wsl" if inside_wsl else "linux"
+        out["inside_wsl"] = inside_wsl
         try:
-            plists = [p for p in agents_dir.glob("com.nexo.*.plist")]
-            out["launch_agents"] = len(plists)
-            out["platform"] = "macos"
+            services = sorted(unit_dir.glob("nexo-*.service")) if unit_dir.is_dir() else []
+            timers = sorted(unit_dir.glob("nexo-*.timer")) if unit_dir.is_dir() else []
+            out["systemd_services"] = len(services)
+            out["systemd_timers"] = len(timers)
         except Exception as exc:
             out["error"] = str(exc)
-    else:
-        out["platform"] = "unknown"
+            out["status"] = "degraded"
+            return out
+        if inside_wsl:
+            out["windows_host_tasks"] = query_windows_host_tasks()
+        out["status"] = "ok" if (out.get("systemd_services", 0) or out.get("systemd_timers", 0)) else "degraded"
+        if out["status"] == "degraded":
+            out["reason"] = "no_nexo_systemd_units_detected"
+        return out
+
+    if system == "Windows":
+        out["platform"] = "windows"
+        out["windows_host_tasks"] = query_windows_host_tasks()
+        out["status"] = "ok" if out["windows_host_tasks"].get("available") else "degraded"
+        if out["status"] == "degraded":
+            out["reason"] = "windows_task_scheduler_unavailable"
+        return out
+
+    out["platform"] = "unknown"
     out["status"] = "ok"
     return out
 

package/src/requirements.txt

@@ -12,8 +12,11 @@ tomli; python_version < "3.11"
 anthropic>=0.80.0
 openai>=2.20.0
 
-# Embedding model (optional but recommended for cognitive features)
-fastembed
+# Embedding model (optional but recommended for cognitive features).
+# Pin >=0.8.0: older releases require Python <3.12 and pip iterates each
+# obsolete version for ~10 min on Ubuntu 24.04 (Python 3.12) before finding
+# a compatible one. Verified empirically during Win11 clean install bootstrap.
+fastembed>=0.8.0
 
 # Dashboard (optional, only needed for `python -m dashboard.app`)
 fastapi

package/src/support_snapshot.py

@@ -20,7 +20,7 @@ import paths
 from doctor.formatters import format_report
 from doctor.orchestrator import run_doctor
 from health_check import collect as collect_health
-from windows_runtime import running_inside_wsl, windows_runtime_status
+from windows_runtime import query_windows_host_tasks, running_inside_wsl, windows_runtime_status
 
 
 def _nexo_home() -> Path:
@@ -125,6 +125,9 @@ def collect_snapshot(*, log_lines: int = 80, include_doctor: bool = False) -> di
             "is_wsl": running_inside_wsl(system=system, release=release),
         },
         "windows_runtime": windows_runtime_status(_nexo_home(), system=system, release=release),
+        "windows_host": {
+            "tasks": query_windows_host_tasks(),
+        },
         "paths": _path_status(),
         "health": collect_health(),
         "logs": _recent_logs(log_lines),

package/src/windows_runtime.py

@@ -1,8 +1,13 @@
 """Helpers for Windows/WSL runtime diagnostics."""
 from __future__ import annotations
 
+import csv
+import io
+import json
 import os
 import platform
+import shutil
+import subprocess
 from pathlib import Path
 from typing import Any
 
@@ -36,6 +41,257 @@ def is_windows_mount_path(candidate: Path) -> bool:
     return normalized.startswith("/mnt/")
 
 
+def _default_windows_runner(args: list[str], *, timeout: int = 20) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+
+
+def resolve_windows_host_binary(
+    command: str,
+    *,
+    which_func=shutil.which,
+) -> str:
+    direct = str(which_func(command) or "").strip()
+    if direct:
+        return direct
+    fallbacks = {
+        "powershell.exe": [
+            "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe",
+            "/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe",
+        ],
+        "schtasks.exe": [
+            "/mnt/c/Windows/System32/schtasks.exe",
+            "/c/Windows/System32/schtasks.exe",
+        ],
+    }
+    for candidate in fallbacks.get(command.lower(), ()):
+        if Path(candidate).exists():
+            return candidate
+    return ""
+
+
+def windows_host_interop_available(*, which_func=shutil.which) -> bool:
+    return bool(
+        resolve_windows_host_binary("powershell.exe", which_func=which_func)
+        or resolve_windows_host_binary("schtasks.exe", which_func=which_func)
+    )
+
+
+def query_windows_host_special_folders(
+    *,
+    runner=_default_windows_runner,
+    which_func=shutil.which,
+) -> dict[str, Any]:
+    powershell = resolve_windows_host_binary("powershell.exe", which_func=which_func)
+    if not powershell:
+        return {
+            "available": False,
+            "error": "powershell_missing",
+            "folders": {},
+        }
+
+    script = (
+        "$obj = [ordered]@{"
+        "LocalApplicationData=[Environment]::GetFolderPath('LocalApplicationData');"
+        "ApplicationData=[Environment]::GetFolderPath('ApplicationData');"
+        "Programs=[Environment]::GetFolderPath('Programs')"
+        "};"
+        "$obj | ConvertTo-Json -Compress"
+    )
+    try:
+        result = runner([powershell, "-NoProfile", "-Command", script], timeout=20)
+    except Exception as exc:
+        return {
+            "available": False,
+            "error": str(exc),
+            "folders": {},
+        }
+    raw = str(result.stdout or "").strip()
+    if result.returncode != 0 or not raw:
+        return {
+            "available": False,
+            "error": str(result.stderr or result.stdout or "windows_special_folders_failed").strip(),
+            "folders": {},
+        }
+    try:
+        payload = json.loads(raw)
+    except Exception as exc:
+        return {
+            "available": False,
+            "error": f"invalid_json: {exc}",
+            "folders": {},
+        }
+    if not isinstance(payload, dict):
+        return {
+            "available": False,
+            "error": "invalid_payload",
+            "folders": {},
+        }
+    folders = {str(key): str(value or "").strip() for key, value in payload.items()}
+    return {
+        "available": True,
+        "folders": folders,
+    }
+
+
+def query_windows_host_tasks(
+    *,
+    runner=_default_windows_runner,
+    which_func=shutil.which,
+) -> dict[str, Any]:
+    schtasks = resolve_windows_host_binary("schtasks.exe", which_func=which_func)
+    if not schtasks:
+        return {
+            "available": False,
+            "error": "schtasks_missing",
+            "tasks": [],
+        }
+
+    try:
+        result = runner([schtasks, "/Query", "/FO", "CSV", "/NH"], timeout=30)
+    except Exception as exc:
+        return {
+            "available": False,
+            "error": str(exc),
+            "tasks": [],
+        }
+
+    if result.returncode != 0:
+        return {
+            "available": False,
+            "error": str(result.stderr or result.stdout or "schtasks_query_failed").strip(),
+            "tasks": [],
+        }
+
+    tasks: list[str] = []
+    try:
+        reader = csv.reader(io.StringIO(str(result.stdout or "")))
+        for row in reader:
+            if not row:
+                continue
+            name = str(row[0] or "").strip()
+            if name and "nexo" in name.lower():
+                tasks.append(name)
+    except Exception as exc:
+        return {
+            "available": False,
+            "error": f"invalid_csv: {exc}",
+            "tasks": [],
+        }
+
+    return {
+        "available": True,
+        "tasks": sorted(set(tasks)),
+    }
+
+
+def build_windows_host_cleanup_plan(
+    *,
+    delete_data: bool = False,
+    runner=_default_windows_runner,
+    which_func=shutil.which,
+) -> dict[str, Any]:
+    folders_payload = query_windows_host_special_folders(runner=runner, which_func=which_func)
+    tasks_payload = query_windows_host_tasks(runner=runner, which_func=which_func)
+    folders = folders_payload.get("folders", {}) if folders_payload.get("available") else {}
+    local = str(folders.get("LocalApplicationData", "")).strip()
+    roaming = str(folders.get("ApplicationData", "")).strip()
+    programs = str(folders.get("Programs", "")).strip()
+
+    runtime_paths = [
+        path for path in (
+            f"{local}\\Programs\\NEXO Desktop" if local else "",
+            f"{local}\\Programs\\NEXO Desktop Support" if local else "",
+        ) if path
+    ]
+    data_paths = [
+        path for path in (
+            f"{roaming}\\NEXO Desktop" if roaming else "",
+            f"{roaming}\\NEXO Desktop Support" if roaming else "",
+            f"{local}\\NEXO Desktop" if local else "",
+            f"{local}\\NEXO Desktop Support" if local else "",
+        ) if path
+    ]
+    shortcut_paths = [
+        path for path in (
+            f"{programs}\\NEXO Desktop.lnk" if programs else "",
+            f"{programs}\\NEXO Desktop Support.lnk" if programs else "",
+        ) if path
+    ]
+    return {
+        "available": bool(folders_payload.get("available") or tasks_payload.get("available")),
+        "folders": folders,
+        "runtime_paths": runtime_paths,
+        "data_paths": data_paths if delete_data else [],
+        "shortcut_paths": shortcut_paths,
+        "tasks": list(tasks_payload.get("tasks", [])),
+        "errors": [
+            value for value in (
+                folders_payload.get("error"),
+                tasks_payload.get("error"),
+            ) if value
+        ],
+    }
+
+
+def cleanup_windows_host_artifacts(
+    *,
+    delete_data: bool = False,
+    dry_run: bool = False,
+    runner=_default_windows_runner,
+    which_func=shutil.which,
+) -> dict[str, Any]:
+    powershell = resolve_windows_host_binary("powershell.exe", which_func=which_func)
+    schtasks = resolve_windows_host_binary("schtasks.exe", which_func=which_func)
+    plan = build_windows_host_cleanup_plan(
+        delete_data=delete_data,
+        runner=runner,
+        which_func=which_func,
+    )
+    actions: list[dict[str, str]] = []
+    errors = list(plan.get("errors", []))
+
+    for path in plan["runtime_paths"]:
+        actions.append({"category": "remove-win-host-app", "detail": Path(path).name, "path": path})
+    for path in plan["shortcut_paths"]:
+        actions.append({"category": "remove-win-host-shortcut", "detail": Path(path).name, "path": path})
+    for path in plan["data_paths"]:
+        actions.append({"category": "remove-win-host-data", "detail": Path(path).name, "path": path})
+    for task_name in plan["tasks"]:
+        actions.append({"category": "remove-win-host-task", "detail": task_name, "path": task_name})
+
+    if dry_run or not plan["available"]:
+        return {"available": plan["available"], "actions": actions, "errors": errors}
+
+    if powershell:
+        remove_targets = plan["runtime_paths"] + plan["shortcut_paths"] + plan["data_paths"]
+        if remove_targets:
+            quoted = ", ".join(json.dumps(target) for target in remove_targets)
+            script = (
+                f"$targets = @({quoted}); "
+                "foreach ($target in $targets) { "
+                "if (Test-Path -LiteralPath $target) { "
+                "Remove-Item -LiteralPath $target -Recurse -Force -ErrorAction SilentlyContinue "
+                "} }"
+            )
+            try:
+                result = runner([powershell, "-NoProfile", "-Command", script], timeout=60)
+                if result.returncode != 0:
+                    errors.append(str(result.stderr or result.stdout or "windows_remove_failed").strip())
+            except Exception as exc:
+                errors.append(str(exc))
+
+    if schtasks:
+        for task_name in plan["tasks"]:
+            try:
+                result = runner([schtasks, "/Delete", "/TN", task_name, "/F"], timeout=20)
+                if result.returncode != 0:
+                    errors.append(str(result.stderr or result.stdout or f"task_delete_failed:{task_name}").strip())
+            except Exception as exc:
+                errors.append(f"{task_name}: {exc}")
+
+    return {"available": plan["available"], "actions": actions, "errors": errors}
+
+
 def windows_runtime_status(nexo_home: Path, *, system: str | None = None, release: str | None = None) -> dict[str, Any]:
     resolved_system = str(system or platform.system() or "").strip()
     resolved_release = str(release or platform.release() or "").strip()
@@ -63,6 +319,7 @@ def windows_runtime_status(nexo_home: Path, *, system: str | None = None, releas
         "inside_wsl": inside_wsl,
         "windows_host_bridge": running_from_windows_host(),
         "bridge_mode": bridge_mode(),
+        "windows_host_interop": windows_host_interop_available(),
         "wsl_distro": str(os.environ.get("WSL_DISTRO_NAME", "")).strip(),
         "wsl_interop": bool(str(os.environ.get("WSL_INTEROP", "")).strip()),
         "nexo_home_on_windows_mount": on_windows_mount,