fix(paths): respect OPENCLAW_HOME for all internal path resolution (#12091)

* fix(paths): respect OPENCLAW_HOME for all internal path resolution (#11995)

Add home-dir module (src/infra/home-dir.ts) that centralizes home
directory resolution with precedence: OPENCLAW_HOME > HOME > USERPROFILE > os.homedir().

Migrate all path-sensitive callsites: config IO, agent dirs, session
transcripts, pairing store, cron store, doctor, CLI profiles.

Add envHomedir() helper in config/paths.ts to reduce lambda noise.
Document OPENCLAW_HOME in docs/help/environment.md.

* fix(paths): handle OPENCLAW_HOME '~' fallback (#12091) (thanks @sebslight)

* docs: mention OPENCLAW_HOME in install and getting started (#12091) (thanks @sebslight)

* fix(status): show OPENCLAW_HOME in shortened paths (#12091) (thanks @sebslight)

* docs(changelog): clarify OPENCLAW_HOME and HOME precedence (#12091) (thanks @sebslight)

src/infra/home-dir.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { expandHomePrefix, resolveEffectiveHomeDir, resolveRequiredHomeDir } from "./home-dir.js";
+
+describe("resolveEffectiveHomeDir", () => {
+  it("prefers OPENCLAW_HOME over HOME and USERPROFILE", () => {
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+      USERPROFILE: "C:/Users/other",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveEffectiveHomeDir(env, () => "/fallback")).toBe("/srv/openclaw-home");
+  });
+
+  it("falls back to HOME then USERPROFILE then homedir", () => {
+    expect(resolveEffectiveHomeDir({ HOME: "/home/alice" } as NodeJS.ProcessEnv)).toBe(
+      "/home/alice",
+    );
+    expect(resolveEffectiveHomeDir({ USERPROFILE: "C:/Users/alice" } as NodeJS.ProcessEnv)).toBe(
+      "C:/Users/alice",
+    );
+    expect(resolveEffectiveHomeDir({} as NodeJS.ProcessEnv, () => "/fallback")).toBe("/fallback");
+  });
+
+  it("expands OPENCLAW_HOME when set to ~", () => {
+    const env = {
+      OPENCLAW_HOME: "~/svc",
+      HOME: "/home/alice",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveEffectiveHomeDir(env)).toBe("/home/alice/svc");
+  });
+});
+
+describe("resolveRequiredHomeDir", () => {
+  it("returns cwd when no home source is available", () => {
+    expect(
+      resolveRequiredHomeDir({} as NodeJS.ProcessEnv, () => {
+        throw new Error("no home");
+      }),
+    ).toBe(process.cwd());
+  });
+
+  it("returns cwd when OPENCLAW_HOME is tilde-only and no fallback home exists", () => {
+    expect(
+      resolveRequiredHomeDir({ OPENCLAW_HOME: "~" } as NodeJS.ProcessEnv, () => {
+        throw new Error("no home");
+      }),
+    ).toBe(process.cwd());
+  });
+});
+
+describe("expandHomePrefix", () => {
+  it("expands tilde using effective home", () => {
+    const value = expandHomePrefix("~/x", {
+      env: { OPENCLAW_HOME: "/srv/openclaw-home" } as NodeJS.ProcessEnv,
+    });
+    expect(value).toBe("/srv/openclaw-home/x");
+  });
+
+  it("keeps non-tilde values unchanged", () => {
+    expect(expandHomePrefix("/tmp/x")).toBe("/tmp/x");
+  });
+});

src/infra/home-dir.ts

@@ -0,0 +1,71 @@
+import os from "node:os";
+
+function normalize(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveEffectiveHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string | undefined {
+  const explicitHome = normalize(env.OPENCLAW_HOME);
+  if (explicitHome) {
+    if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
+      const fallbackHome =
+        normalize(env.HOME) ?? normalize(env.USERPROFILE) ?? normalizeSafe(homedir);
+      if (fallbackHome) {
+        return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
+      }
+      return undefined;
+    }
+    return explicitHome;
+  }
+
+  const envHome = normalize(env.HOME);
+  if (envHome) {
+    return envHome;
+  }
+
+  const userProfile = normalize(env.USERPROFILE);
+  if (userProfile) {
+    return userProfile;
+  }
+
+  return normalizeSafe(homedir);
+}
+
+function normalizeSafe(homedir: () => string): string | undefined {
+  try {
+    return normalize(homedir());
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveRequiredHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  return resolveEffectiveHomeDir(env, homedir) ?? process.cwd();
+}
+
+export function expandHomePrefix(
+  input: string,
+  opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+  },
+): string {
+  if (!input.startsWith("~")) {
+    return input;
+  }
+  const home =
+    normalize(opts?.home) ??
+    resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+  if (!home) {
+    return input;
+  }
+  return input.replace(/^~(?=$|[\\/])/, home);
+}