nexu-io
diff --git a/‎AGENTS.md‎
Lines changed: 13 additions & 4 deletions b/‎AGENTS.md‎
Lines changed: 13 additions & 4 deletions
diff --git a/‎apps/desktop/main/index.ts‎
Lines changed: 120 additions & 29 deletions b/‎apps/desktop/main/index.ts‎
Lines changed: 120 additions & 29 deletions
diff --git a/‎apps/desktop/main/ipc.ts‎
Lines changed: 4 additions & 0 deletions b/‎apps/desktop/main/ipc.ts‎
Lines changed: 4 additions & 0 deletions
@@ -69,12 +69,21 @@ This repo is desktop-first. Prefer the controller-first path and remove or ignor
 - The desktop dev launcher is `apps/desktop/dev.sh`; it is the source of truth for tmux orchestration, sidecar builds, runtime cleanup, and stable repo-local path setup during local development.
 - Treat `pnpm start` as the canonical cold-start entrypoint for the full local desktop runtime.
 - The active desktop runtime path is controller-first: desktop launches `controller + web + openclaw` and no longer starts local `api`, `gateway`, or `pglite` sidecars.
-- Desktop local runtime should not depend on PostgreSQL. In dev mode, all state (config, OpenClaw state, logs) lives under `.tmp/desktop/nexu-home/`, fully isolated from the packaged app's `~/.nexu/`. Launchd plists go to `.tmp/launchd/`, runtime-ports.json also lives there.
-- In packaged mode, state lives under `~/.nexu/`, plists under `~/Library/LaunchAgents/`, logs under `~/.nexu/logs/`.
+- Desktop local runtime should not depend on PostgreSQL. In dev mode, all state (config, OpenClaw state, logs) lives under `.tmp/desktop/nexu-home/`, fully isolated from the packaged app. Launchd plists go to `.tmp/launchd/`, runtime-ports.json also lives there.
+- In packaged mode, data is split across two directories (see table below). Launchd plists go to `~/Library/LaunchAgents/`.
 - Local desktop runtime state is repo-scoped under `.tmp/desktop/` in development.
+
+### Packaged app directory layout
+
+| Directory | Purpose | Survives uninstall |
+|---|---|---|
+| `~/.nexu/` (`NEXU_HOME`) | User config (`config.json`, `cloud-profiles.json`), compiled snapshots, skill ledger, skillhub cache, logs, openclaw-sidecar, `nexu.db` | Yes |
+| `~/Library/Application Support/@nexu/desktop/` (Electron `userData`) | OpenClaw runtime state: `runtime/openclaw/state/agents/` (conversations), `runtime/openclaw/state/extensions/` (channel state), `runtime/openclaw/state/skills/`, `runtime/openclaw/state/openclaw.json`, plus Electron internal data (Cache, IndexedDB, etc.) | No (cleaned by uninstall tools) |
+
+The split is intentional: `NEXU_HOME` holds lightweight user preferences that should persist across reinstalls; Electron `userData` holds heavy runtime state tied to the app lifecycle. `OPENCLAW_STATE_DIR` is explicitly set by the desktop launcher to point to the `userData` path — do not rely on the controller's default fallback.
 - For startup troubleshooting, use `pnpm logs` to tail dev logs.
-- `pnpm reset-state` is a dev-only cleanup shortcut; it stops the stack and removes repo-local desktop runtime state under `.tmp/desktop/`, but it does not delete packaged app state in `~/.nexu/`.
-- To fully reset local desktop + controller state, stop the stack, remove `.tmp/desktop/`, then remove `~/.nexu/`.
+- `pnpm reset-state` is a dev-only cleanup shortcut; it stops the stack and removes repo-local desktop runtime state under `.tmp/desktop/`, but it does not delete packaged app state.
+- To fully reset local desktop + controller state, stop the stack, remove `.tmp/desktop/`, then remove `~/.nexu/` and `~/Library/Application Support/@nexu/desktop/`.
 - If `pnpm start` exits immediately because `electron/cli.js` cannot be resolved from `apps/desktop`, validate `pnpm -C apps/desktop exec electron --version` and consult `specs/guides/desktop-runtime-guide.md` before changing the launcher flow.
 - Desktop already exposes an agent-friendly runtime observability surface; prefer subscribing/querying before adding temporary UI or ad hoc debug logging.
 - For deeper desktop runtime inspection, use the existing event/query path (`onRuntimeEvent(...)`, `runtime:query-events`, `queryRuntimeEvents(...)`) instead of rebuilding one-off diagnostics.
 
@@ -12,6 +12,7 @@ import {
   powerSaveBlocker,
   shell,
 } from "electron";
+import { getOpenclawSkillsDir } from "../shared/desktop-paths";
 import type { DesktopChromeMode, DesktopSurface } from "../shared/host";
 import { getDesktopRuntimeConfig } from "../shared/runtime-config";
 import { getDesktopSentryBuildMetadata } from "../shared/sentry-build-metadata";
@@ -24,8 +25,12 @@ import {
   setUpdateManager,
 } from "./ipc";
 import { RuntimeOrchestrator } from "./runtime/daemon-supervisor";
-import { createRuntimeUnitManifests } from "./runtime/manifests";
 import {
+  buildSkillNodePath,
+  createRuntimeUnitManifests,
+} from "./runtime/manifests";
+import {
+  type PortAllocation,
   PortAllocationError,
   allocateDesktopRuntimePorts,
 } from "./runtime/port-allocation";
@@ -36,12 +41,18 @@ import {
 } from "./runtime/runtime-logger";
 import {
   type LaunchdBootstrapResult,
+  SERVICE_LABELS,
   bootstrapWithLaunchd,
   getDefaultPlistDir,
+  getLogDir,
   installLaunchdQuitHandler,
   isLaunchdBootstrapEnabled,
   resolveLaunchdPaths,
 } from "./services";
+import {
+  getLegacyNexuHomeStateDir,
+  migrateOpenclawState,
+} from "./services/state-migration";
 import { SleepGuard, type SleepGuardLogEntry } from "./sleep-guard";
 import { ComponentUpdater } from "./updater/component-updater";
 import { StartupHealthCheck } from "./updater/rollback";
@@ -75,19 +86,27 @@ const baseRuntimeConfig = getDesktopRuntimeConfig(process.env, {
   resourcesPath: app.isPackaged ? electronRoot : undefined,
   useBuildConfig: app.isPackaged,
 });
-const { allocations: runtimePortAllocations, runtimeConfig } =
-  await allocateDesktopRuntimePorts(process.env, baseRuntimeConfig).catch(
-    (error: unknown) => {
-      if (error instanceof PortAllocationError) {
-        throw new Error(
-          `[desktop:ports] ${error.code} purpose=${error.purpose} ` +
-            `preferredPort=${error.preferredPort ?? "n/a"} ${error.message}`,
-        );
-      }
+// In launchd mode, skip port probing — the bootstrap has its own port
+// recovery via runtime-ports.json and handles leftover processes gracefully.
+// Probing here would waste time and the results get overridden by attach anyway.
+const useLaunchdMode = isLaunchdBootstrapEnabled();
+const { allocations: runtimePortAllocations, runtimeConfig } = useLaunchdMode
+  ? {
+      allocations: [] as PortAllocation[],
+      runtimeConfig: baseRuntimeConfig,
+    }
+  : await allocateDesktopRuntimePorts(process.env, baseRuntimeConfig).catch(
+      (error: unknown) => {
+        if (error instanceof PortAllocationError) {
+          throw new Error(
+            `[desktop:ports] ${error.code} purpose=${error.purpose} ` +
+              `preferredPort=${error.preferredPort ?? "n/a"} ${error.message}`,
+          );
+        }
 
-      throw error;
-    },
-  );
+        throw error;
+      },
+    );
 const orchestrator = new RuntimeOrchestrator(
   createRuntimeUnitManifests(
     electronRoot,
@@ -225,6 +244,14 @@ let diagnosticsReporter: DesktopDiagnosticsReporter | null = null;
 let sleepGuard: SleepGuard | null = null;
 let launchdResult: LaunchdBootstrapResult | null = null;
 
+// Cold-start gate: IPC handler for `env:get-runtime-config` waits for this
+// promise to resolve before returning, ensuring the renderer always gets the
+// final config with correct ports (not the pre-cold-start defaults).
+let resolveColdStartReady: () => void;
+const coldStartReady = new Promise<void>((r) => {
+  resolveColdStartReady = r;
+});
+
 logLaunchTimeline(
   `runtime ports ${runtimePortAllocations
     .map(
@@ -466,45 +493,107 @@ async function runLaunchdColdStart(): Promise<void> {
   const isDev = !app.isPackaged;
   const paths = resolveLaunchdPaths(app.isPackaged, electronRoot);
 
-  // Derive openclaw paths from nexuHome (must match controller defaults in env.ts)
   const nexuHome = runtimeConfig.paths.nexuHome.replace(
     /^~/,
     process.env.HOME ?? "",
   );
-  const openclawStateDir = resolve(nexuHome, "runtime", "openclaw", "state");
+
+  // In packaged mode, keep openclaw state under Electron userData (matches v0.1.5).
+  // In dev mode, derive from nexuHome for repo-local isolation.
+  const openclawRuntimeRoot = isDev
+    ? resolve(nexuHome, "runtime", "openclaw")
+    : resolve(app.getPath("userData"), "runtime", "openclaw");
+  const openclawStateDir = resolve(openclawRuntimeRoot, "state");
   const openclawConfigPath = resolve(openclawStateDir, "openclaw.json");
 
+  // Migrate any state created under ~/.nexu during v0.1.6 back to userData path
+  if (!isDev) {
+    const legacyStateDir = getLegacyNexuHomeStateDir(
+      runtimeConfig.paths.nexuHome,
+    );
+    if (legacyStateDir !== openclawStateDir) {
+      migrateOpenclawState({
+        targetStateDir: openclawStateDir,
+        sourceStateDir: legacyStateDir,
+        log: (msg) => logColdStart(`state-migration: ${msg}`),
+      });
+    }
+  }
+
   // In dev mode, serve web app from apps/web/dist
   // In packaged mode, serve from resources/web
   const webRoot = isDev
     ? resolve(getWorkspaceRoot(), "apps", "web", "dist")
     : resolve(electronRoot, "runtime", "web", "dist");
 
+  const repoRoot = getWorkspaceRoot();
+  const userDataPath = app.getPath("userData");
+  const openclawSkillsDir = getOpenclawSkillsDir(userDataPath);
+  const openclawTmpDir = resolve(openclawRuntimeRoot, "tmp");
+  const openclawBinPath =
+    process.env.NEXU_OPENCLAW_BIN ?? resolve(paths.openclawCwd, "bin/openclaw");
+  const openclawPackageRoot = resolve(
+    paths.openclawCwd,
+    "node_modules/openclaw",
+  );
+  const openclawExtensionsDir = resolve(openclawPackageRoot, "extensions");
+  const skillhubStaticSkillsDir = app.isPackaged
+    ? resolve(electronRoot, "static/bundled-skills")
+    : resolve(repoRoot, "apps/desktop/static/bundled-skills");
+  const platformTemplatesDir = app.isPackaged
+    ? resolve(electronRoot, "static/platform-templates")
+    : resolve(repoRoot, "apps/controller/static/platform-templates");
+  const skillNodePath = buildSkillNodePath(electronRoot, app.isPackaged);
+
   launchdResult = await bootstrapWithLaunchd({
     isDev,
     controllerPort: runtimeConfig.ports.controller,
     openclawPort: Number(
       new URL(runtimeConfig.urls.openclawBase).port || 18789,
     ),
-    nexuHome: isDev ? nexuHome : undefined,
+    nexuHome,
     gatewayToken: isDev ? undefined : runtimeConfig.tokens.gateway,
     webPort: runtimeConfig.ports.web,
     webRoot,
     plistDir: getDefaultPlistDir(isDev),
     ...paths,
     openclawConfigPath,
     openclawStateDir,
+    // Controller-specific env vars
+    webUrl: runtimeConfig.urls.web,
+    openclawSkillsDir,
+    skillhubStaticSkillsDir,
+    platformTemplatesDir,
+    openclawBinPath,
+    openclawExtensionsDir,
+    skillNodePath,
+    openclawTmpDir,
   });
 
-  if (launchdResult.attachedPorts) {
-    // Attached to existing services — override runtimeConfig with actual ports
-    const { controllerPort, openclawPort, webPort } =
-      launchdResult.attachedPorts;
-    runtimeConfig.ports.controller = controllerPort;
-    runtimeConfig.ports.web = webPort;
-    runtimeConfig.urls.controllerBase = `http://127.0.0.1:${controllerPort}`;
-    runtimeConfig.urls.web = `http://127.0.0.1:${webPort}`;
-    runtimeConfig.urls.openclawBase = `http://127.0.0.1:${openclawPort}`;
+  // Wire launchd-managed units into the orchestrator so the control plane
+  // shows correct status, and Start/Stop buttons work via launchd.
+  const launchdLogDir = getLogDir(isDev ? nexuHome : undefined);
+  orchestrator.enableLaunchdMode(
+    launchdResult.launchd,
+    {
+      controller: SERVICE_LABELS.controller(isDev),
+      openclaw: SERVICE_LABELS.openclaw(isDev),
+    },
+    launchdLogDir,
+  );
+
+  // Always sync runtimeConfig with actual effective ports — these may differ
+  // from the initial config if ports were recovered from a previous session or
+  // OS-assigned due to conflicts.
+  const { controllerPort, openclawPort, webPort } =
+    launchdResult.effectivePorts;
+  runtimeConfig.ports.controller = controllerPort;
+  runtimeConfig.ports.web = webPort;
+  runtimeConfig.urls.controllerBase = `http://127.0.0.1:${controllerPort}`;
+  runtimeConfig.urls.web = `http://127.0.0.1:${webPort}`;
+  runtimeConfig.urls.openclawBase = `http://127.0.0.1:${openclawPort}`;
+
+  if (launchdResult.isAttach) {
     logColdStart(
       `attached to running services (controller=${controllerPort} openclaw=${openclawPort} web=${webPort})`,
     );
@@ -772,7 +861,7 @@ logLaunchTimeline("electron main module evaluated");
 app.whenReady().then(async () => {
   logLaunchTimeline("app.whenReady resolved");
   installApplicationMenu();
-  registerIpcHandlers(orchestrator, runtimeConfig);
+  registerIpcHandlers(orchestrator, runtimeConfig, coldStartReady);
   diagnosticsReporter = new DesktopDiagnosticsReporter(orchestrator);
   const unsubscribeDiagnostics = diagnosticsReporter.start();
   sleepGuard = new SleepGuard({
@@ -797,12 +886,11 @@ app.whenReady().then(async () => {
     }
 
     try {
-      const useLaunchd = isLaunchdBootstrapEnabled();
       logColdStart(
-        `bootstrap mode: ${useLaunchd ? "launchd" : "orchestrator"}`,
+        `bootstrap mode: ${useLaunchdMode ? "launchd" : "orchestrator"}`,
       );
 
-      if (useLaunchd) {
+      if (useLaunchdMode) {
         await runLaunchdColdStart();
       } else {
         await runDesktopColdStart();
@@ -821,6 +909,9 @@ app.whenReady().then(async () => {
         logFilePath: getDesktopLogFilePath("cold-start.log"),
         windowId: getMainWindowId(),
       });
+    } finally {
+      // Unblock renderer — it will get the final config (or show error state)
+      resolveColdStartReady();
     }
 
     // Install launchd quit handler regardless of cold-start success/failure
 
@@ -113,6 +113,7 @@ function assertValidChannel(
 export function registerIpcHandlers(
   orchestrator: RuntimeOrchestrator,
   runtimeConfig: DesktopRuntimeConfig,
+  coldStartReady?: Promise<void>,
 ): void {
   orchestrator.subscribe((runtimeEvent) => {
     for (const window of BrowserWindow.getAllWindows()) {
@@ -191,6 +192,9 @@ export function registerIpcHandlers(
         }
 
         case "env:get-runtime-config": {
+          // Wait for cold-start to finish so the renderer gets final ports
+          // (web port may change due to fallback during bootstrap).
+          if (coldStartReady) await coldStartReady;
           return runtimeConfig;
         }