fix: enable systemd lingering for gateway

src/commands/configure.ts

@@ -53,6 +53,7 @@ import {
 import { setupProviders } from "./onboard-providers.js";
 import { promptRemoteGatewayConfig } from "./onboard-remote.js";
 import { setupSkills } from "./onboard-skills.js";
+import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 
 type WizardSection =
   | "model"
@@ -373,6 +374,8 @@ async function maybeInstallDaemon(params: {
 }) {
   const service = resolveGatewayService();
   const loaded = await service.isLoaded({ env: process.env });
+  let shouldCheckLinger = false;
+  let shouldInstall = true;
   if (loaded) {
     const action = guardCancel(
       await select({
@@ -387,7 +390,8 @@ async function maybeInstallDaemon(params: {
     );
     if (action === "restart") {
       await service.restart({ stdout: process.stdout });
-      return;
+      shouldCheckLinger = true;
+      shouldInstall = false;
     }
     if (action === "skip") return;
     if (action === "reinstall") {
@@ -395,24 +399,37 @@ async function maybeInstallDaemon(params: {
     }
   }
 
-  const devMode =
-    process.argv[1]?.includes(`${path.sep}src${path.sep}`) &&
-    process.argv[1]?.endsWith(".ts");
-  const { programArguments, workingDirectory } =
-    await resolveGatewayProgramArguments({ port: params.port, dev: devMode });
-  const environment: Record<string, string | undefined> = {
-    PATH: process.env.PATH,
-    CLAWDBOT_GATEWAY_TOKEN: params.gatewayToken,
-    CLAWDBOT_LAUNCHD_LABEL:
-      process.platform === "darwin" ? GATEWAY_LAUNCH_AGENT_LABEL : undefined,
-  };
-  await service.install({
-    env: process.env,
-    stdout: process.stdout,
-    programArguments,
-    workingDirectory,
-    environment,
-  });
+  if (shouldInstall) {
+    const devMode =
+      process.argv[1]?.includes(`${path.sep}src${path.sep}`) &&
+      process.argv[1]?.endsWith(".ts");
+    const { programArguments, workingDirectory } =
+      await resolveGatewayProgramArguments({ port: params.port, dev: devMode });
+    const environment: Record<string, string | undefined> = {
+      PATH: process.env.PATH,
+      CLAWDBOT_GATEWAY_TOKEN: params.gatewayToken,
+      CLAWDBOT_LAUNCHD_LABEL:
+        process.platform === "darwin" ? GATEWAY_LAUNCH_AGENT_LABEL : undefined,
+    };
+    await service.install({
+      env: process.env,
+      stdout: process.stdout,
+      programArguments,
+      workingDirectory,
+      environment,
+    });
+    shouldCheckLinger = true;
+  }
+
+  if (shouldCheckLinger) {
+    await ensureSystemdUserLingerInteractive({
+      runtime: params.runtime,
+      prompter: { confirm, note },
+      reason:
+        "Linux installs use a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.",
+      requireConfirm: true,
+    });
+  }
 }
 
 export async function runConfigureWizard(

src/commands/doctor.ts

@@ -31,6 +31,7 @@ import type { RuntimeEnv } from "../runtime.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveUserPath, sleep } from "../utils.js";
 import { healthCommand } from "./health.js";
+import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 import {
   applyWizardMetadata,
   DEFAULT_WORKSPACE,
@@ -599,6 +600,28 @@ export async function doctorCommand(runtime: RuntimeEnv = defaultRuntime) {
 
   await maybeMigrateLegacyGatewayService(cfg, runtime);
 
+  if (process.platform === "linux" && resolveMode(cfg) === "local") {
+    const service = resolveGatewayService();
+    let loaded = false;
+    try {
+      loaded = await service.isLoaded({ env: process.env });
+    } catch {
+      loaded = false;
+    }
+    if (loaded) {
+      await ensureSystemdUserLingerInteractive({
+        runtime,
+        prompter: {
+          confirm: (params) => guardCancel(confirm(params), runtime),
+          note,
+        },
+        reason:
+          "Gateway runs as a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.",
+        requireConfirm: true,
+      });
+    }
+  }
+
   const workspaceDir = resolveUserPath(
     cfg.agent?.workspace ?? DEFAULT_WORKSPACE,
   );

src/commands/onboard-non-interactive.ts

@@ -13,6 +13,7 @@ import { resolveGatewayService } from "../daemon/service.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveUserPath, sleep } from "../utils.js";
+import { ensureSystemdUserLingerNonInteractive } from "./systemd-linger.js";
 import { healthCommand } from "./health.js";
 import { applyMinimaxConfig, setAnthropicApiKey } from "./onboard-auth.js";
 import {
@@ -231,6 +232,7 @@ export async function runNonInteractiveOnboarding(
       workingDirectory,
       environment,
     });
+    await ensureSystemdUserLingerNonInteractive({ runtime });
   }
 
   if (!opts.skipHealth) {

src/commands/systemd-linger.ts

@@ -0,0 +1,109 @@
+import { note } from "@clack/prompts";
+
+import {
+  enableSystemdUserLinger,
+  readSystemdUserLingerStatus,
+} from "../daemon/systemd.js";
+import type { RuntimeEnv } from "../runtime.js";
+
+export type LingerPrompter = {
+  confirm?: (params: { message: string; initialValue?: boolean }) => Promise<
+    boolean
+  >;
+  note: (message: string, title?: string) => Promise<void> | void;
+};
+
+export async function ensureSystemdUserLingerInteractive(params: {
+  runtime: RuntimeEnv;
+  prompter?: LingerPrompter;
+  env?: NodeJS.ProcessEnv;
+  title?: string;
+  reason?: string;
+  prompt?: boolean;
+  requireConfirm?: boolean;
+}): Promise<void> {
+  if (process.platform !== "linux") return;
+  if (params.prompt === false) return;
+  const env = params.env ?? process.env;
+  const prompter = params.prompter ?? { note };
+  const title = params.title ?? "Systemd";
+  const status = await readSystemdUserLingerStatus(env);
+  if (!status) {
+    await prompter.note(
+      "Unable to read loginctl linger status. Ensure systemd + loginctl are available.",
+      title,
+    );
+    return;
+  }
+  if (status.linger === "yes") return;
+
+  const reason =
+    params.reason ??
+    "Systemd user services stop when you log out or go idle, which kills the Gateway.";
+  const actionNote = params.requireConfirm
+    ? "We can enable lingering now (needs sudo; writes /var/lib/systemd/linger)."
+    : "Enabling lingering now (needs sudo; writes /var/lib/systemd/linger).";
+  await prompter.note(
+    `${reason}\n${actionNote}`,
+    title,
+  );
+
+  if (params.requireConfirm && prompter.confirm) {
+    const ok = await prompter.confirm({
+      message: `Enable systemd lingering for ${status.user}?`,
+      initialValue: true,
+    });
+    if (!ok) {
+      await prompter.note(
+        "Without lingering, the Gateway will stop when you log out.",
+        title,
+      );
+      return;
+    }
+  }
+
+  const result = await enableSystemdUserLinger({
+    env,
+    user: status.user,
+    sudoMode: "prompt",
+  });
+  if (result.ok) {
+    await prompter.note(
+      `Enabled systemd lingering for ${status.user}.`,
+      title,
+    );
+    return;
+  }
+
+  params.runtime.error(
+    `Failed to enable lingering: ${result.stderr || result.stdout || "unknown error"}`,
+  );
+  await prompter.note(
+    `Run manually: sudo loginctl enable-linger ${status.user}`,
+    title,
+  );
+}
+
+export async function ensureSystemdUserLingerNonInteractive(params: {
+  runtime: RuntimeEnv;
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  if (process.platform !== "linux") return;
+  const env = params.env ?? process.env;
+  const status = await readSystemdUserLingerStatus(env);
+  if (!status || status.linger === "yes") return;
+
+  const result = await enableSystemdUserLinger({
+    env,
+    user: status.user,
+    sudoMode: "non-interactive",
+  });
+  if (result.ok) {
+    params.runtime.log(`Enabled systemd lingering for ${status.user}.`);
+    return;
+  }
+
+  params.runtime.log(
+    `Systemd lingering is disabled for ${status.user}. Run: sudo loginctl enable-linger ${status.user}`,
+  );
+}

src/daemon/systemd.test.ts

@@ -0,0 +1,44 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { readSystemdUserLingerStatus } from "./systemd.js";
+import { runExec } from "../process/exec.js";
+
+vi.mock("../process/exec.js", () => ({
+  runExec: vi.fn(),
+  runCommandWithTimeout: vi.fn(),
+}));
+
+const runExecMock = vi.mocked(runExec);
+
+describe("readSystemdUserLingerStatus", () => {
+  beforeEach(() => {
+    runExecMock.mockReset();
+  });
+
+  it("returns yes when loginctl reports Linger=yes", async () => {
+    runExecMock.mockResolvedValue({
+      stdout: "Linger=yes\n",
+      stderr: "",
+    });
+    const result = await readSystemdUserLingerStatus({ USER: "tobi" });
+    expect(result).toEqual({ user: "tobi", linger: "yes" });
+  });
+
+  it("returns no when loginctl reports Linger=no", async () => {
+    runExecMock.mockResolvedValue({
+      stdout: "Linger=no\n",
+      stderr: "",
+    });
+    const result = await readSystemdUserLingerStatus({ USER: "tobi" });
+    expect(result).toEqual({ user: "tobi", linger: "no" });
+  });
+
+  it("returns null when Linger is missing", async () => {
+    runExecMock.mockResolvedValue({
+      stdout: "UID=1000\n",
+      stderr: "",
+    });
+    const result = await readSystemdUserLingerStatus({ USER: "tobi" });
+    expect(result).toBeNull();
+  });
+});

src/daemon/systemd.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 
@@ -7,6 +8,7 @@ import {
   GATEWAY_SYSTEMD_SERVICE_NAME,
   LEGACY_GATEWAY_SYSTEMD_SERVICE_NAMES,
 } from "./constants.js";
+import { runCommandWithTimeout, runExec } from "../process/exec.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -30,6 +32,83 @@ function resolveSystemdUnitPath(
   return resolveSystemdUnitPathForName(env, GATEWAY_SYSTEMD_SERVICE_NAME);
 }
 
+function resolveLoginctlUser(
+  env: Record<string, string | undefined>,
+): string | null {
+  const fromEnv = env.USER?.trim() || env.LOGNAME?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    return os.userInfo().username;
+  } catch {
+    return null;
+  }
+}
+
+export type SystemdUserLingerStatus = {
+  user: string;
+  linger: "yes" | "no";
+};
+
+export async function readSystemdUserLingerStatus(
+  env: Record<string, string | undefined>,
+): Promise<SystemdUserLingerStatus | null> {
+  const user = resolveLoginctlUser(env);
+  if (!user) return null;
+  try {
+    const { stdout } = await runExec(
+      "loginctl",
+      ["show-user", user, "-p", "Linger"],
+      { timeoutMs: 5_000 },
+    );
+    const line = stdout
+      .split("\n")
+      .map((entry) => entry.trim())
+      .find((entry) => entry.startsWith("Linger="));
+    const value = line?.split("=")[1]?.trim().toLowerCase();
+    if (value === "yes" || value === "no") {
+      return { user, linger: value };
+    }
+  } catch {
+    // ignore; loginctl may be unavailable
+  }
+  return null;
+}
+
+export async function enableSystemdUserLinger(params: {
+  env: Record<string, string | undefined>;
+  user?: string;
+  sudoMode?: "prompt" | "non-interactive";
+}): Promise<{ ok: boolean; stdout: string; stderr: string; code: number }> {
+  const user = params.user ?? resolveLoginctlUser(params.env);
+  if (!user) {
+    return { ok: false, stdout: "", stderr: "Missing user", code: 1 };
+  }
+  const needsSudo =
+    typeof process.getuid === "function" ? process.getuid() !== 0 : true;
+  const sudoArgs =
+    needsSudo && params.sudoMode !== undefined
+      ? ["sudo", ...(params.sudoMode === "non-interactive" ? ["-n"] : [])]
+      : [];
+  const argv = [
+    ...sudoArgs,
+    "loginctl",
+    "enable-linger",
+    user,
+  ];
+  try {
+    const result = await runCommandWithTimeout(argv, { timeoutMs: 30_000 });
+    return {
+      ok: result.code === 0,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      code: result.code ?? 1,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, stdout: "", stderr: message, code: 1 };
+  }
+}
+
 function systemdEscapeArg(value: string): string {
   if (!/[\s"\\]/.test(value)) return value;
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;

src/wizard/onboarding.ts

@@ -34,6 +34,7 @@ import {
 import { setupProviders } from "../commands/onboard-providers.js";
 import { promptRemoteGatewayConfig } from "../commands/onboard-remote.js";
 import { setupSkills } from "../commands/onboard-skills.js";
+import { ensureSystemdUserLingerInteractive } from "../commands/systemd-linger.js";
 import type {
   AuthChoice,
   GatewayAuthChoice,
@@ -537,6 +538,17 @@ export async function runOnboardingWizard(
         environment,
       });
     }
+
+    await ensureSystemdUserLingerInteractive({
+      runtime,
+      prompter: {
+        confirm: prompter.confirm,
+        note: prompter.note,
+      },
+      reason:
+        "Linux installs use a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.",
+      requireConfirm: true,
+    });
   }
 
   await sleep(1500);