fix: align linux service PATH + tests (#1512) (thanks @robbyczgw-cla)

- Test Linux user directories included when HOME is set
- Test Linux user directories excluded when HOME is missing
- Test path ordering (extraDirs > user dirs > system dirs)
- Test platform-specific behavior (Linux vs macOS vs Windows)
- Test buildMinimalServicePath() with HOME in env

Covers getMinimalServicePathParts() and buildMinimalServicePath()
for all Linux user bin directory edge cases.

Test count: 7 → 16 (+9 tests)

CHANGELOG.md

@@ -11,6 +11,7 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - TUI: forward unknown slash commands (for example, `/context`) to the Gateway.
 - Media: preserve PNG alpha when possible; fall back to JPEG when still over size cap. (#1491) Thanks @robbyczgw-cla.
+- Gateway/Linux: include user + env-configured bin dirs in systemd PATH and align service audit checks. (#1512) Thanks @robbyczgw-cla.
 - Agents: treat plugin-only tool allowlists as opt-ins; keep core tools enabled. (#1467)
 
 ## 2026.1.22

src/daemon/service-audit.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { buildMinimalServicePath } from "./service-env.js";
 import { auditGatewayServiceConfig, SERVICE_AUDIT_CODES } from "./service-audit.js";
 
 describe("auditGatewayServiceConfig", () => {
@@ -39,4 +40,24 @@ describe("auditGatewayServiceConfig", () => {
       audit.issues.some((issue) => issue.code === SERVICE_AUDIT_CODES.gatewayPathMissingDirs),
     ).toBe(true);
   });
+
+  it("accepts Linux minimal PATH with user directories", async () => {
+    const env = { HOME: "/home/testuser", PNPM_HOME: "/opt/pnpm" };
+    const minimalPath = buildMinimalServicePath({ platform: "linux", env });
+    const audit = await auditGatewayServiceConfig({
+      env,
+      platform: "linux",
+      command: {
+        programArguments: ["/usr/bin/node", "gateway"],
+        environment: { PATH: minimalPath },
+      },
+    });
+
+    expect(
+      audit.issues.some((issue) => issue.code === SERVICE_AUDIT_CODES.gatewayPathNonMinimal),
+    ).toBe(false);
+    expect(
+      audit.issues.some((issue) => issue.code === SERVICE_AUDIT_CODES.gatewayPathMissingDirs),
+    ).toBe(false);
+  });
 });

src/daemon/service-audit.ts

@@ -206,6 +206,7 @@ function normalizePathEntry(entry: string, platform: NodeJS.Platform): string {
 function auditGatewayServicePath(
   command: GatewayServiceCommand,
   issues: ServiceConfigIssue[],
+  env: Record<string, string | undefined>,
   platform: NodeJS.Platform,
 ) {
   if (platform === "win32") return;
@@ -219,12 +220,13 @@ function auditGatewayServicePath(
     return;
   }
 
-  const expected = getMinimalServicePathParts({ platform });
+  const expected = getMinimalServicePathParts({ platform, home: env.HOME, env });
   const parts = servicePath
     .split(getPathModule(platform).delimiter)
     .map((entry) => entry.trim())
     .filter(Boolean);
   const normalizedParts = parts.map((entry) => normalizePathEntry(entry, platform));
+  const normalizedExpected = new Set(expected.map((entry) => normalizePathEntry(entry, platform)));
   const missing = expected.filter((entry) => {
     const normalized = normalizePathEntry(entry, platform);
     return !normalizedParts.includes(normalized);
@@ -239,6 +241,9 @@ function auditGatewayServicePath(
 
   const nonMinimal = parts.filter((entry) => {
     const normalized = normalizePathEntry(entry, platform);
+    if (normalizedExpected.has(normalized)) {
+      return false;
+    }
     return (
       normalized.includes("/.nvm/") ||
       normalized.includes("/.fnm/") ||
@@ -315,7 +320,7 @@ export async function auditGatewayServiceConfig(params: {
   const platform = params.platform ?? process.platform;
 
   auditGatewayCommand(params.command?.programArguments, issues);
-  auditGatewayServicePath(params.command, issues, platform);
+  auditGatewayServicePath(params.command, issues, params.env, platform);
   await auditGatewayRuntime(params.env, params.command, issues, platform);
 
   if (platform === "linux") {

src/daemon/service-env.test.ts

@@ -4,8 +4,122 @@ import {
   buildMinimalServicePath,
   buildNodeServiceEnvironment,
   buildServiceEnvironment,
+  getMinimalServicePathParts,
 } from "./service-env.js";
 
+describe("getMinimalServicePathParts - Linux user directories", () => {
+  it("includes user bin directories when HOME is set on Linux", () => {
+    const result = getMinimalServicePathParts({
+      platform: "linux",
+      home: "/home/testuser",
+    });
+
+    // Should include all common user bin directories
+    expect(result).toContain("/home/testuser/.local/bin");
+    expect(result).toContain("/home/testuser/.npm-global/bin");
+    expect(result).toContain("/home/testuser/bin");
+    expect(result).toContain("/home/testuser/.nvm/current/bin");
+    expect(result).toContain("/home/testuser/.fnm/current/bin");
+    expect(result).toContain("/home/testuser/.volta/bin");
+    expect(result).toContain("/home/testuser/.asdf/shims");
+    expect(result).toContain("/home/testuser/.local/share/pnpm");
+    expect(result).toContain("/home/testuser/.bun/bin");
+  });
+
+  it("excludes user bin directories when HOME is undefined on Linux", () => {
+    const result = getMinimalServicePathParts({
+      platform: "linux",
+      home: undefined,
+    });
+
+    // Should only include system directories
+    expect(result).toEqual(["/usr/local/bin", "/usr/bin", "/bin"]);
+
+    // Should not include any user-specific paths
+    expect(result.some((p) => p.includes(".local"))).toBe(false);
+    expect(result.some((p) => p.includes(".npm-global"))).toBe(false);
+    expect(result.some((p) => p.includes(".nvm"))).toBe(false);
+  });
+
+  it("places user directories before system directories on Linux", () => {
+    const result = getMinimalServicePathParts({
+      platform: "linux",
+      home: "/home/testuser",
+    });
+
+    const userDirIndex = result.indexOf("/home/testuser/.local/bin");
+    const systemDirIndex = result.indexOf("/usr/bin");
+
+    expect(userDirIndex).toBeGreaterThan(-1);
+    expect(systemDirIndex).toBeGreaterThan(-1);
+    expect(userDirIndex).toBeLessThan(systemDirIndex);
+  });
+
+  it("places extraDirs before user directories on Linux", () => {
+    const result = getMinimalServicePathParts({
+      platform: "linux",
+      home: "/home/testuser",
+      extraDirs: ["/custom/bin"],
+    });
+
+    const extraDirIndex = result.indexOf("/custom/bin");
+    const userDirIndex = result.indexOf("/home/testuser/.local/bin");
+
+    expect(extraDirIndex).toBeGreaterThan(-1);
+    expect(userDirIndex).toBeGreaterThan(-1);
+    expect(extraDirIndex).toBeLessThan(userDirIndex);
+  });
+
+  it("includes env-configured bin roots when HOME is set on Linux", () => {
+    const result = getMinimalServicePathParts({
+      platform: "linux",
+      home: "/home/testuser",
+      env: {
+        PNPM_HOME: "/opt/pnpm",
+        NPM_CONFIG_PREFIX: "/opt/npm",
+        BUN_INSTALL: "/opt/bun",
+        VOLTA_HOME: "/opt/volta",
+        ASDF_DATA_DIR: "/opt/asdf",
+        NVM_DIR: "/opt/nvm",
+        FNM_DIR: "/opt/fnm",
+      },
+    });
+
+    expect(result).toContain("/opt/pnpm");
+    expect(result).toContain("/opt/npm/bin");
+    expect(result).toContain("/opt/bun/bin");
+    expect(result).toContain("/opt/volta/bin");
+    expect(result).toContain("/opt/asdf/shims");
+    expect(result).toContain("/opt/nvm/current/bin");
+    expect(result).toContain("/opt/fnm/current/bin");
+  });
+
+  it("does not include Linux user directories on macOS", () => {
+    const result = getMinimalServicePathParts({
+      platform: "darwin",
+      home: "/Users/testuser",
+    });
+
+    // Should not include Linux-specific user dirs even with HOME set
+    expect(result.some((p) => p.includes(".npm-global"))).toBe(false);
+    expect(result.some((p) => p.includes(".nvm"))).toBe(false);
+
+    // Should only include macOS system directories
+    expect(result).toContain("/opt/homebrew/bin");
+    expect(result).toContain("/usr/local/bin");
+  });
+
+  it("does not include Linux user directories on Windows", () => {
+    const result = getMinimalServicePathParts({
+      platform: "win32",
+      home: "C:\\Users\\testuser",
+    });
+
+    // Windows returns empty array (uses existing PATH)
+    expect(result).toEqual([]);
+  });
+});
+
 describe("buildMinimalServicePath", () => {
   it("includes Homebrew + system dirs on macOS", () => {
     const result = buildMinimalServicePath({
@@ -26,6 +140,51 @@ describe("buildMinimalServicePath", () => {
     expect(result).toBe("C:\\\\Windows\\\\System32");
   });
 
+  it("includes Linux user directories when HOME is set in env", () => {
+    const result = buildMinimalServicePath({
+      platform: "linux",
+      env: { HOME: "/home/alice" },
+    });
+    const parts = result.split(path.delimiter);
+
+    // Verify user directories are included
+    expect(parts).toContain("/home/alice/.local/bin");
+    expect(parts).toContain("/home/alice/.npm-global/bin");
+    expect(parts).toContain("/home/alice/.nvm/current/bin");
+
+    // Verify system directories are also included
+    expect(parts).toContain("/usr/local/bin");
+    expect(parts).toContain("/usr/bin");
+    expect(parts).toContain("/bin");
+  });
+
+  it("excludes Linux user directories when HOME is not in env", () => {
+    const result = buildMinimalServicePath({
+      platform: "linux",
+      env: {},
+    });
+    const parts = result.split(path.delimiter);
+
+    // Should only have system directories
+    expect(parts).toEqual(["/usr/local/bin", "/usr/bin", "/bin"]);
+
+    // No user-specific paths
+    expect(parts.some((p) => p.includes("home"))).toBe(false);
+  });
+
+  it("ensures user directories come before system directories on Linux", () => {
+    const result = buildMinimalServicePath({
+      platform: "linux",
+      env: { HOME: "/home/bob" },
+    });
+    const parts = result.split(path.delimiter);
+
+    const firstUserDirIdx = parts.indexOf("/home/bob/.local/bin");
+    const firstSystemDirIdx = parts.indexOf("/usr/local/bin");
+
+    expect(firstUserDirIdx).toBeLessThan(firstSystemDirIdx);
+  });
+
   it("includes extra directories when provided", () => {
     const result = buildMinimalServicePath({
       platform: "linux",

src/daemon/service-env.ts

@@ -17,6 +17,8 @@ import {
 export type MinimalServicePathOptions = {
   platform?: NodeJS.Platform;
   extraDirs?: string[];
+  home?: string;
+  env?: Record<string, string | undefined>;
 };
 
 type BuildServicePathOptions = MinimalServicePathOptions & {
@@ -33,6 +35,51 @@ function resolveSystemPathDirs(platform: NodeJS.Platform): string[] {
   return [];
 }
 
+/**
+ * Resolve common user bin directories for Linux.
+ * These are paths where npm global installs and node version managers typically place binaries.
+ */
+export function resolveLinuxUserBinDirs(
+  home: string | undefined,
+  env?: Record<string, string | undefined>,
+): string[] {
+  if (!home) return [];
+
+  const dirs: string[] = [];
+
+  const add = (dir: string | undefined) => {
+    if (dir) dirs.push(dir);
+  };
+  const appendSubdir = (base: string | undefined, subdir: string) => {
+    if (!base) return undefined;
+    return base.endsWith(`/${subdir}`) ? base : path.posix.join(base, subdir);
+  };
+
+  // Env-configured bin roots (override defaults when present)
+  add(env?.PNPM_HOME);
+  add(appendSubdir(env?.NPM_CONFIG_PREFIX, "bin"));
+  add(appendSubdir(env?.BUN_INSTALL, "bin"));
+  add(appendSubdir(env?.VOLTA_HOME, "bin"));
+  add(appendSubdir(env?.ASDF_DATA_DIR, "shims"));
+  add(appendSubdir(env?.NVM_DIR, "current/bin"));
+  add(appendSubdir(env?.FNM_DIR, "current/bin"));
+
+  // Common user bin directories
+  dirs.push(`${home}/.local/bin`); // XDG standard, pip, etc.
+  dirs.push(`${home}/.npm-global/bin`); // npm custom prefix (recommended for non-root)
+  dirs.push(`${home}/bin`); // User's personal bin
+
+  // Node version managers
+  dirs.push(`${home}/.nvm/current/bin`); // nvm with current symlink
+  dirs.push(`${home}/.fnm/current/bin`); // fnm
+  dirs.push(`${home}/.volta/bin`); // Volta
+  dirs.push(`${home}/.asdf/shims`); // asdf
+  dirs.push(`${home}/.local/share/pnpm`); // pnpm global bin
+  dirs.push(`${home}/.bun/bin`); // Bun
+
+  return dirs;
+}
+
 export function getMinimalServicePathParts(options: MinimalServicePathOptions = {}): string[] {
   const platform = options.platform ?? process.platform;
   if (platform === "win32") return [];
@@ -41,12 +88,18 @@ export function getMinimalServicePathParts(options: MinimalServicePathOptions =
   const extraDirs = options.extraDirs ?? [];
   const systemDirs = resolveSystemPathDirs(platform);
 
+  // Add Linux user bin directories (npm global, nvm, fnm, volta, etc.)
+  const linuxUserDirs =
+    platform === "linux" ? resolveLinuxUserBinDirs(options.home, options.env) : [];
+
   const add = (dir: string) => {
     if (!dir) return;
     if (!parts.includes(dir)) parts.push(dir);
   };
 
   for (const dir of extraDirs) add(dir);
+  // User dirs first so user-installed binaries take precedence
+  for (const dir of linuxUserDirs) add(dir);
   for (const dir of systemDirs) add(dir);
 
   return parts;
@@ -59,7 +112,10 @@ export function buildMinimalServicePath(options: BuildServicePathOptions = {}):
     return env.PATH ?? "";
   }
 
-  return getMinimalServicePathParts(options).join(path.delimiter);
+  return getMinimalServicePathParts({
+    ...options,
+    home: options.home ?? env.HOME,
+  }).join(path.delimiter);
 }
 
 export function buildServiceEnvironment(params: {

test/setup.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, vi } from "vitest";
+import { afterAll, afterEach, beforeEach, vi } from "vitest";
 
 import type {
   ChannelId,
@@ -9,6 +9,10 @@ import type { ClawdbotConfig } from "../src/config/config.js";
 import type { OutboundSendDeps } from "../src/infra/outbound/deliver.js";
 import { setActivePluginRegistry } from "../src/plugins/runtime.js";
 import { createTestRegistry } from "../src/test-utils/channel-plugins.js";
+import { installTestEnv } from "./test-env";
+
+const testEnv = installTestEnv();
+afterAll(() => testEnv.cleanup());
 const pickSendFn = (id: ChannelId, deps?: OutboundSendDeps) => {
   switch (id) {
     case "discord":

vitest.config.ts

@@ -26,7 +26,6 @@ export default defineConfig({
       "test/format-error.test.ts",
     ],
     setupFiles: ["test/setup.ts"],
-    globalSetup: ["test/global-setup.ts"],
     exclude: [
       "dist/**",
       "apps/macos/**",

vitest.e2e.config.ts

@@ -11,7 +11,6 @@ export default defineConfig({
     maxWorkers: e2eWorkers,
     include: ["test/**/*.e2e.test.ts", "src/**/*.e2e.test.ts"],
     setupFiles: ["test/setup.ts"],
-    globalSetup: ["test/global-setup.ts"],
     exclude: [
       "dist/**",
       "apps/macos/**",