doctor: warn on macOS cloud-synced state directories (#31004)

* Doctor: detect macOS cloud-synced state directories

* Doctor tests: cover cloud-synced macOS state detection

* Docs: note cloud-synced state warning in doctor guide

* Docs: recommend local macOS state dir placement

* Changelog: add macOS cloud-synced state dir warning

* Changelog: credit macOS cloud state warning PR

* Doctor state: anchor cloud-sync roots to macOS home

* Doctor tests: cover OPENCLAW_HOME cloud-sync override

* Doctor state: prefer resolved target for cloud detection

* Doctor tests: cover local-target cloud symlink case

src/commands/doctor-state-integrity.cloud-storage.test.ts

@@ -0,0 +1,128 @@
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { detectMacCloudSyncedStateDir } from "./doctor-state-integrity.js";
+
+describe("detectMacCloudSyncedStateDir", () => {
+  const home = "/Users/tester";
+
+  it("detects state dir under iCloud Drive", () => {
+    const stateDir = path.join(
+      home,
+      "Library",
+      "Mobile Documents",
+      "com~apple~CloudDocs",
+      "OpenClaw",
+      ".openclaw",
+    );
+
+    const result = detectMacCloudSyncedStateDir(stateDir, {
+      platform: "darwin",
+      homedir: home,
+    });
+
+    expect(result).toEqual({
+      path: path.resolve(stateDir),
+      storage: "iCloud Drive",
+    });
+  });
+
+  it("detects state dir under Library/CloudStorage", () => {
+    const stateDir = path.join(home, "Library", "CloudStorage", "Dropbox", "OpenClaw", ".openclaw");
+
+    const result = detectMacCloudSyncedStateDir(stateDir, {
+      platform: "darwin",
+      homedir: home,
+    });
+
+    expect(result).toEqual({
+      path: path.resolve(stateDir),
+      storage: "CloudStorage provider",
+    });
+  });
+
+  it("detects cloud-synced target when state dir resolves via symlink", () => {
+    const symlinkPath = "/tmp/openclaw-state";
+    const resolvedCloudPath = path.join(
+      home,
+      "Library",
+      "CloudStorage",
+      "OneDrive-Personal",
+      "OpenClaw",
+      ".openclaw",
+    );
+
+    const result = detectMacCloudSyncedStateDir(symlinkPath, {
+      platform: "darwin",
+      homedir: home,
+      resolveRealPath: () => resolvedCloudPath,
+    });
+
+    expect(result).toEqual({
+      path: path.resolve(resolvedCloudPath),
+      storage: "CloudStorage provider",
+    });
+  });
+
+  it("ignores cloud-synced symlink prefix when resolved target is local", () => {
+    const symlinkPath = path.join(
+      home,
+      "Library",
+      "CloudStorage",
+      "OneDrive-Personal",
+      "OpenClaw",
+      ".openclaw",
+    );
+    const resolvedLocalPath = path.join(home, ".openclaw");
+
+    const result = detectMacCloudSyncedStateDir(symlinkPath, {
+      platform: "darwin",
+      homedir: home,
+      resolveRealPath: () => resolvedLocalPath,
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("anchors cloud detection to OS homedir when OPENCLAW_HOME is overridden", () => {
+    const stateDir = path.join(home, "Library", "CloudStorage", "iCloud Drive", ".openclaw");
+    const originalOpenClawHome = process.env.OPENCLAW_HOME;
+    process.env.OPENCLAW_HOME = "/tmp/openclaw-home-override";
+    const homedirSpy = vi.spyOn(os, "homedir").mockReturnValue(home);
+    try {
+      const result = detectMacCloudSyncedStateDir(stateDir, {
+        platform: "darwin",
+      });
+
+      expect(result).toEqual({
+        path: path.resolve(stateDir),
+        storage: "CloudStorage provider",
+      });
+    } finally {
+      homedirSpy.mockRestore();
+      if (originalOpenClawHome === undefined) {
+        delete process.env.OPENCLAW_HOME;
+      } else {
+        process.env.OPENCLAW_HOME = originalOpenClawHome;
+      }
+    }
+  });
+
+  it("returns null outside darwin", () => {
+    const stateDir = path.join(
+      home,
+      "Library",
+      "Mobile Documents",
+      "com~apple~CloudDocs",
+      "OpenClaw",
+      ".openclaw",
+    );
+
+    const result = detectMacCloudSyncedStateDir(stateDir, {
+      platform: "linux",
+      homedir: home,
+    });
+
+    expect(result).toBeNull();
+  });
+});